@moretea-labs/forge 1.8.0 → 1.8.1

package/src/runtime/root/workflow-supervisor-runtime.ts

@@ -0,0 +1,209 @@
+import { once } from 'node:events';
+import { WorkflowSupervisorControlPlane } from '../../../supervisor/control-plane';
+import { forgeWorkflowSupervisorValidators } from '../../../supervisor/forge-validators';
+import { forgeWorkflowSupervisorLifecycleHooks } from './workflow-supervisor-composition';
+import { resolveWorkflowSupervisorForgeHome, workflowSupervisorSocketPath } from '../../../supervisor/paths';
+import {
+  createWorkflowSupervisorServer,
+  reconcileWorkflowSupervisorSocket,
+  WorkflowSupervisorEphemeralDiscovery,
+} from '../../../supervisor/server';
+import { startWorkflowSupervisorNativeBrowserAdapter, type WorkflowSupervisorNativeBrowserHandle, type WorkflowSupervisorStallProjection, type WorkflowSupervisorTransportProjection } from '../../../supervisor/native-browser-adapter';
+import type { WorkflowSupervisorConsumerStatus } from '../../../supervisor/types';
+import { WorkflowSupervisorStore } from '../../../supervisor/store';
+import { createComputerInteractionTargetAuthority } from '../../../adapters/computer/interaction-target-authority';
+import { MacOsChatgptConversationTargetPort } from '../plugins/computer-chatgpt-macos-target';
+import { ChromeExtensionChatgptConversationTargetPort } from '../../../adapters/computer/chatgpt-extension-target';
+import { PreferredChatgptConversationTargetPort } from '../../../adapters/computer/chatgpt-target-router';
+import { createRuntimeComputerTargetPersistence } from './computer-target-persistence';
+import { listDirectActivities, listUserRequests, recordDirectActivity, recordUserRequest, resolveUserRequest } from '../../../packages/kernel/identity/api/index';
+import { getRuntimeWriteClaim } from './write-fence';
+
+export interface RuntimeWorkflowSupervisorHandle {
+  readonly done: Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * Workflow Supervisor is a distinct lifecycle authority, not a distinct OS
+ * service. Canonical Forge Runtime already owns the durable process lifecycle;
+ * this composition gives Supervisor one in-process server/writer while keeping
+ * its SQLite and Unix socket authority isolated under the exact Controller Home.
+ */
+export function startWorkflowSupervisorRuntime(controllerHome: string): Promise<RuntimeWorkflowSupervisorHandle>;
+export function startWorkflowSupervisorRuntime(
+  controllerHome: string,
+  options: { nativeBrowserAdapter?: boolean },
+): Promise<RuntimeWorkflowSupervisorHandle>;
+export async function startWorkflowSupervisorRuntime(
+  controllerHome: string,
+  options: { nativeBrowserAdapter?: boolean } = {},
+): Promise<RuntimeWorkflowSupervisorHandle> {
+  const forgeHome = resolveWorkflowSupervisorForgeHome(controllerHome);
+  const socketPath = workflowSupervisorSocketPath(forgeHome);
+  const claim = getRuntimeWriteClaim();
+  const writer = claim && !claim.unmanaged
+    ? { runtimeInstanceId: claim.runtimeInstanceId, fencingGeneration: claim.fencingGeneration, pid: claim.ownerPid }
+    : undefined;
+  if (writer) await reconcileWorkflowSupervisorSocket({ socketPath, incoming: writer });
+  const store = new WorkflowSupervisorStore(forgeHome, {
+    activeReleaseId: () => getRuntimeWriteClaim()?.releaseId,
+  });
+  const controlPlane = new WorkflowSupervisorControlPlane(
+    store,
+    forgeWorkflowSupervisorValidators(),
+    forgeWorkflowSupervisorLifecycleHooks(controllerHome),
+  );
+  const discovery = new WorkflowSupervisorEphemeralDiscovery();
+  const browserAdapterEnabled = true;
+  const nativeBrowserAdapterEnabled = options.nativeBrowserAdapter !== false;
+  let nativeBrowser: WorkflowSupervisorNativeBrowserHandle | undefined;
+  const transportActivityId = (taskId?: string): string => `workflow-supervisor-transport-${(taskId ?? 'instance').replace(/[^a-zA-Z0-9._-]/g, '_')}`;
+  const reportTransportState = (projection: WorkflowSupervisorTransportProjection): void => {
+    const activityId = transportActivityId(projection.taskId);
+    const existing = listDirectActivities(controllerHome, 200).find((item) => item.activityId === activityId);
+    const recovered = projection.state === 'recovered';
+    recordDirectActivity(controllerHome, {
+      activityId,
+      capabilityId: 'workflow-supervisor.transport',
+      kind: 'direct_execution',
+      targetScope: projection.taskId ? `workflow-supervisor-task:${projection.taskId}` : 'workflow-supervisor:instance',
+      principalId: 'forge-runtime',
+      status: recovered ? 'completed' : 'running',
+      startedAt: existing?.startedAt ?? projection.firstFailureAt ?? projection.observedAt,
+      ...(recovered ? { completedAt: projection.observedAt } : {}),
+      summary: recovered
+        ? 'Workflow Supervisor transport recovered; autonomous continuation resumed without user action.'
+        : `Workflow Supervisor transport is temporarily degraded and auto-recovering${projection.code ? ` (${projection.code})` : ''}. Durable task/effect progress is preserved.`,
+    });
+    if (recovered && projection.taskId) {
+      const prefix = `workflow-supervisor.transport-human:${projection.taskId}:`;
+      for (const request of listUserRequests(controllerHome, 'pending').filter((item) => item.rootCauseKey.startsWith(prefix))) {
+        resolveUserRequest(controllerHome, { requestId: request.requestId, decision: 'transport_recovered', resolvedBy: 'forge-runtime' });
+      }
+    }
+  };
+  const stallActivityId = (taskId: string): string => `workflow-supervisor-stall-${taskId.replace(/[^a-zA-Z0-9._-]/g, '_')}`;
+  const reportTaskStall = (projection: WorkflowSupervisorStallProjection): void => {
+    const activityId = stallActivityId(projection.taskId);
+    const existing = listDirectActivities(controllerHome, 200).find((item) => item.activityId === activityId);
+    const exhausted = projection.state === 'exhausted';
+    if (!exhausted && !existing) return;
+    const budget = projection.generations !== undefined && projection.maxGenerations !== undefined
+      ? ` (${projection.generations}/${projection.maxGenerations})`
+      : '';
+    recordDirectActivity(controllerHome, {
+      activityId,
+      capabilityId: 'workflow-supervisor.continuation',
+      kind: 'direct_execution',
+      targetScope: `workflow-supervisor-task:${projection.taskId}`,
+      principalId: 'forge-runtime',
+      status: exhausted ? 'running' : 'completed',
+      startedAt: existing?.startedAt ?? projection.observedAt,
+      ...(!exhausted ? { completedAt: projection.observedAt } : {}),
+      summary: exhausted
+        ? projection.stallKind === 'provider_resume_exhausted'
+          ? 'Workflow Supervisor exhausted bounded provider-resume attempts. The committed effect is preserved; only read-only reconciliation for late receipt evidence continues, and no duplicate provider turn will be sent.'
+          : `Workflow Supervisor exhausted bounded automatic dispatch generations${budget}. The task/effect remains durable, but automatic sending is paused until explicit recovery or new authoritative evidence; no duplicate provider turn will be sent.`
+        : 'Workflow Supervisor continuation stall cleared; the durable task/effect can progress again.',
+    });
+  };
+  const requestHumanAction = (input: { taskId: string; effectId?: string; action: 'login' | 'grant_permission'; code: string }): void => {
+    const actionLabel = input.action === 'login' ? 'sign in to ChatGPT' : 'restore browser automation permission';
+    recordUserRequest(controllerHome, {
+      kind: 'user_action_request',
+      rootCauseKey: `workflow-supervisor.transport-human:${input.taskId}:${input.action}`,
+      title: input.action === 'login' ? 'ChatGPT sign-in required' : 'Browser permission required',
+      summary: `Workflow Supervisor cannot continue this task until you ${actionLabel}. The task and effect ledger are preserved and will resume automatically afterward.`,
+      actionRequired: input.action,
+      targetScope: { scopeKind: 'workflow_supervisor_task', scopeId: input.taskId },
+      presentation: {
+        severity: 'blocked',
+        creationReason: 'workflow_supervisor_transport_human_boundary',
+        reason: input.code,
+        currentState: { taskId: input.taskId, ...(input.effectId ? { effectId: input.effectId } : {}), transportCode: input.code },
+      },
+    });
+  };
+  const targetAuthority = createComputerInteractionTargetAuthority(createRuntimeComputerTargetPersistence());
+  const extensionTargetPort = new ChromeExtensionChatgptConversationTargetPort(controllerHome, targetAuthority);
+  const appleEventsTargetPort = new MacOsChatgptConversationTargetPort(controllerHome, targetAuthority);
+  const targetPort = new PreferredChatgptConversationTargetPort(extensionTargetPort, appleEventsTargetPort);
+  const browserConsumerStatus = (): WorkflowSupervisorConsumerStatus => nativeBrowser?.status() ?? {
+    enabled: browserAdapterEnabled,
+    running: false,
+    observedAt: new Date().toISOString(),
+    transportFailureStreak: 0,
+    providerBackpressureMs: 0,
+    stalled: false,
+  };
+  const server = createWorkflowSupervisorServer({
+    controlPlane,
+    socketPath,
+    discovery,
+    browserAdapterEnabled,
+    browserConsumerStatus,
+    computerExtensionBroker: extensionTargetPort,
+    ...(writer ? { writer } : {}),
+  });
+  const done = once(server, 'close').then(() => undefined);
+  await once(server, 'listening');
+  let closing = false;
+  let reconciliationInFlight: Promise<void> | undefined;
+  const reconcileCommittedContinuations = (): void => {
+    if (closing || reconciliationInFlight) return;
+    reconciliationInFlight = controlPlane.reconcileCommittedContinuations()
+      .then(() => undefined)
+      .catch((error) => { process.stderr.write(`[workflow-supervisor-reconcile] ${error instanceof Error ? error.message : String(error)}\\n`); })
+      .finally(() => { reconciliationInFlight = undefined; });
+  };
+  // Reconcile before browser polling starts so a Runtime restart can finish a
+  // previously committed CONTINUE without requiring another user/provider turn.
+  reconcileCommittedContinuations();
+  // Reconciliation is a core Runtime responsibility. Keep this timer referenced
+  // for the whole Runtime lifetime instead of treating continuation delivery as
+  // best-effort background work.
+  const reconciliationTimer = setInterval(reconcileCommittedContinuations, 2_000);
+  if (nativeBrowserAdapterEnabled) {
+    nativeBrowser = startWorkflowSupervisorNativeBrowserAdapter(controlPlane, discovery, {
+      targetPort,
+      nowMs: () => Date.now(),
+      // Liveness authority for one applied provider turn. Live evidence: these
+      // Supervisor turns run for 10-50 minutes, so any quiet window shorter than
+      // that reserved duplicate recovery prompts on turns that were still
+      // working (60s and then 3 minutes both fired in production). This is the
+      // existing bounded maximum, and the digest itself now tracks live turn
+      // activity, so the window only elapses on a genuinely silent surface. A
+      // real provider failure is classified from provider failure text
+      // independently of this threshold.
+      providerIdleGraceMs: 10 * 60_000,
+      providerScopeKey: controllerHome,
+      sleep: async (ms) => { await new Promise((resolve) => setTimeout(resolve, ms)); },
+      setInterval: (handler, ms) => setInterval(handler, ms),
+      clearInterval: (timer) => clearInterval(timer),
+      onError: (error) => { process.stderr.write(`[workflow-supervisor-computer-target] ${error instanceof Error ? error.message : String(error)}\\n`); },
+      reportTransportState,
+      reportTaskStall,
+      requestHumanAction,
+    });
+  }
+  return {
+    done,
+    async close(): Promise<void> {
+      if (closing) return;
+      closing = true;
+      clearInterval(reconciliationTimer);
+      try {
+        await reconciliationInFlight?.catch(() => undefined);
+        await nativeBrowser?.close().catch(() => undefined);
+        if (server.listening) {
+          await new Promise<void>((resolve, reject) => {
+            server.close((error) => error ? reject(error) : resolve());
+          });
+        }
+      } finally {
+        store.close();
+      }
+    },
+  };
+}

package/src/runtime/root/write-fence.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'path';
 import { resolveControllerHome } from '../../cli/repositories/controller-home';
 import { isProcessAlive } from '../shared/process-tree';
-import { readRuntimeOwner, type RuntimeOwnerRecord } from './ownership';
+import { readRuntimeIncarnation, readRuntimeOwner, type RuntimeOwnerRecord } from './ownership';
 import {
   readRuntimeReleaseAuthority,
   type RuntimeReleaseAuthority,
@@ -29,6 +29,7 @@ export type RuntimeWriteAction = (typeof RUNTIME_WRITE_ACTIONS)[number];
 export interface RuntimeWriteClaim {
   controllerHome: string;
   runtimeInstanceId: string;
+  fencingGeneration: number;
   ownerPid: number;
   releaseAuthorityRevision: number;
   releaseFencingToken: string;
@@ -50,6 +51,7 @@ export interface RuntimeWriteFenceCheck {
 export const RUNTIME_WRITE_CLAIM_ENV = {
   controllerHome: 'FORGE_CONTROLLER_HOME',
   runtimeInstanceId: 'FORGE_RUNTIME_INSTANCE_ID',
+  fencingGeneration: 'FORGE_RUNTIME_INCARNATION_GENERATION',
   ownerPid: 'FORGE_RUNTIME_OWNER_PID',
   releaseAuthorityRevision: 'FORGE_RELEASE_AUTHORITY_REVISION',
   releaseFencingToken: 'FORGE_RELEASE_FENCING_TOKEN',
@@ -75,6 +77,7 @@ function claimFromAuthority(
   return {
     controllerHome: resolveControllerHome(controllerHome),
     runtimeInstanceId: owner.runtimeInstanceId,
+    fencingGeneration: owner.fencingGeneration ?? 0,
     ownerPid: owner.pid,
     releaseAuthorityRevision: authority.revision,
     releaseFencingToken: authority.fencingToken,
@@ -85,11 +88,22 @@ function claimFromAuthority(
   };
 }
 
+export function currentRuntimeWriteClaimEnvironment(controllerHome: string): Record<string, string> {
+  const home = resolveControllerHome(controllerHome);
+  const owner = readRuntimeOwner(home);
+  const authority = readRuntimeReleaseAuthority(home);
+  if (!owner || !authority) {
+    throw new Error('RUNTIME_WRITE_CLAIM_BIND_FAILED: Runtime owner or release authority is missing');
+  }
+  return runtimeWriteClaimEnvironment(claimFromAuthority(home, owner, authority));
+}
+
 export function runtimeWriteClaimEnvironment(claim: RuntimeWriteClaim): Record<string, string> {
   if (claim.unmanaged) return {};
   return {
     [RUNTIME_WRITE_CLAIM_ENV.controllerHome]: claim.controllerHome,
     [RUNTIME_WRITE_CLAIM_ENV.runtimeInstanceId]: claim.runtimeInstanceId,
+    [RUNTIME_WRITE_CLAIM_ENV.fencingGeneration]: String(claim.fencingGeneration),
     [RUNTIME_WRITE_CLAIM_ENV.ownerPid]: String(claim.ownerPid),
     [RUNTIME_WRITE_CLAIM_ENV.releaseAuthorityRevision]: String(claim.releaseAuthorityRevision),
     [RUNTIME_WRITE_CLAIM_ENV.releaseFencingToken]: claim.releaseFencingToken,
@@ -130,6 +144,7 @@ export const clearRuntimeWriteClaimForTests = clearRuntimeWriteClaim;
 export function bindRuntimeWriteClaim(input: {
   controllerHome: string;
   runtimeInstanceId?: string;
+  fencingGeneration?: number;
   ownerPid?: number;
   releaseAuthorityRevision?: number;
   releaseFencingToken?: string;
@@ -146,6 +161,7 @@ export function bindRuntimeWriteClaim(input: {
 
   const explicit = {
     runtimeInstanceId: input.runtimeInstanceId?.trim(),
+    fencingGeneration: input.fencingGeneration,
     ownerPid: input.ownerPid,
     releaseAuthorityRevision: input.releaseAuthorityRevision,
     releaseFencingToken: input.releaseFencingToken?.trim(),
@@ -157,6 +173,7 @@ export function bindRuntimeWriteClaim(input: {
   const hasAnyExplicit = explicitValues.some((value) => value !== undefined && value !== '');
   const hasFullExplicit = Boolean(
     explicit.runtimeInstanceId
+    && Number.isInteger(explicit.fencingGeneration) && explicit.fencingGeneration! > 0
     && Number.isInteger(explicit.ownerPid) && explicit.ownerPid! > 0
     && Number.isInteger(explicit.releaseAuthorityRevision) && explicit.releaseAuthorityRevision! > 0
     && explicit.releaseFencingToken
@@ -169,6 +186,7 @@ export function bindRuntimeWriteClaim(input: {
     return installClaim({
       controllerHome: home,
       runtimeInstanceId: explicit.runtimeInstanceId!,
+      fencingGeneration: explicit.fencingGeneration!,
       ownerPid: explicit.ownerPid!,
       releaseAuthorityRevision: explicit.releaseAuthorityRevision!,
       releaseFencingToken: explicit.releaseFencingToken!,
@@ -190,6 +208,7 @@ export function bindRuntimeWriteClaim(input: {
     return installClaim({
       controllerHome: home,
       runtimeInstanceId: `unmanaged-${process.pid}`,
+      fencingGeneration: 0,
       ownerPid: process.pid,
       releaseAuthorityRevision: 0,
       releaseFencingToken: 'unmanaged',
@@ -220,6 +239,7 @@ export function bindInheritedRuntimeWriteClaimFromEnvironment(
   return bindRuntimeWriteClaim({
     controllerHome,
     runtimeInstanceId,
+    fencingGeneration: positiveInteger(env[RUNTIME_WRITE_CLAIM_ENV.fencingGeneration]),
     ownerPid: positiveInteger(env[RUNTIME_WRITE_CLAIM_ENV.ownerPid]),
     releaseAuthorityRevision: positiveInteger(env[RUNTIME_WRITE_CLAIM_ENV.releaseAuthorityRevision]),
     releaseFencingToken: env[RUNTIME_WRITE_CLAIM_ENV.releaseFencingToken]?.trim(),
@@ -256,6 +276,7 @@ export function assertRuntimeMayWrite(
   const home = explicitHome ?? claim?.controllerHome;
   if (!home) return { allowed: true, reason: 'unbound_no_controller_home' };
   const owner = readRuntimeOwner(home);
+  const incarnation = readRuntimeIncarnation(home);
   const authority = readRuntimeReleaseAuthority(home);
   if (!claim) {
     if (!owner && !authority) return { allowed: true, reason: 'unbound_no_runtime_authority' };
@@ -276,9 +297,18 @@ export function assertRuntimeMayWrite(
   }
   if (!owner) return { allowed: false, reason: 'runtime_owner_missing', authority };
   if (!isProcessAlive(owner.pid)) return { allowed: false, reason: 'runtime_owner_dead', owner, authority };
+  if (!incarnation) return { allowed: false, reason: 'runtime_incarnation_missing', owner, authority };
+  if (
+    incarnation.runtimeInstanceId !== owner.runtimeInstanceId
+    || incarnation.pid !== owner.pid
+    || incarnation.fencingGeneration !== (owner.fencingGeneration ?? 0)
+  ) return { allowed: false, reason: 'runtime_incarnation_authority_mismatch', owner, authority };
   if (owner.runtimeInstanceId !== claim.runtimeInstanceId) {
     return { allowed: false, reason: 'runtime_instance_fenced', owner, authority };
   }
+  if (incarnation.fencingGeneration !== claim.fencingGeneration) {
+    return { allowed: false, reason: 'runtime_incarnation_generation_fenced', owner, authority };
+  }
   if (owner.pid !== claim.ownerPid) return { allowed: false, reason: 'runtime_owner_pid_fenced', owner, authority };
   if (!authority) return { allowed: false, reason: 'runtime_release_authority_missing', owner };
   if (authority.revision !== claim.releaseAuthorityRevision) {
@@ -299,11 +329,29 @@ export function assertRuntimeMayWrite(
   return { allowed: true, owner, authority };
 }
 
+export class RuntimeWriteFenceError extends Error {
+  readonly code = 'WRITER_FENCED' as const;
+
+  constructor(
+    readonly action: RuntimeWriteAction,
+    readonly reason: string,
+  ) {
+    super(`WRITER_FENCED:${action}:${reason}`);
+    this.name = 'RuntimeWriteFenceError';
+  }
+}
+
+export function isRuntimeWriteFenceError(error: unknown): error is RuntimeWriteFenceError {
+  return Boolean(error
+    && typeof error === 'object'
+    && (error as { code?: unknown }).code === 'WRITER_FENCED');
+}
+
 export function assertRuntimeMayWriteOrThrow(
   action: RuntimeWriteAction,
   controllerHomeOverride?: string,
 ): RuntimeReleaseAuthority | undefined {
   const check = assertRuntimeMayWrite(action, controllerHomeOverride);
-  if (!check.allowed) throw new Error(`WRITER_FENCED:${action}:${check.reason ?? 'denied'}`);
+  if (!check.allowed) throw new RuntimeWriteFenceError(action, check.reason ?? 'denied');
   return check.authority;
 }

package/src/runtime/safe-tooling/google-credential-store.ts

@@ -1,30 +1,38 @@
 import { execFileSync } from 'child_process';
 
 export type StoredGoogleService = 'gmail' | 'calendar' | 'tasks' | 'google-workspace';
+export type StoredGoogleCredentialKind = 'refresh-token' | 'client-secret';
 
 export interface GoogleCredentialStoreAdapter {
   available(): boolean;
-  read(service: StoredGoogleService): string | undefined;
-  write(service: StoredGoogleService, refreshToken: string): void;
+  read(service: StoredGoogleService, kind?: StoredGoogleCredentialKind): string | undefined;
+  write(service: StoredGoogleService, value: string, kind?: StoredGoogleCredentialKind): void;
 }
 
 const KEYCHAIN_SERVICE_PREFIX = 'forge.google-oauth';
-const KEYCHAIN_ACCOUNT = 'refresh-token';
-const memoryCache = new Map<StoredGoogleService, string>();
+const KEYCHAIN_ACCOUNT: Record<StoredGoogleCredentialKind, string> = {
+  'refresh-token': 'refresh-token',
+  'client-secret': 'client-secret',
+};
+const memoryCache = new Map<string, string>();
 
 function keychainService(service: StoredGoogleService): string {
   return `${KEYCHAIN_SERVICE_PREFIX}.${service}`;
 }
 
+function cacheKey(service: StoredGoogleService, kind: StoredGoogleCredentialKind): string {
+  return `${service}:${kind}`;
+}
+
 const macKeychainAdapter: GoogleCredentialStoreAdapter = {
   available: () => process.platform === 'darwin',
-  read(service) {
+  read(service, kind = 'refresh-token') {
     if (process.platform !== 'darwin') return undefined;
     try {
       const value = execFileSync('/usr/bin/security', [
         'find-generic-password',
         '-s', keychainService(service),
-        '-a', KEYCHAIN_ACCOUNT,
+        '-a', KEYCHAIN_ACCOUNT[kind],
         '-w',
       ], {
         encoding: 'utf-8',
@@ -36,7 +44,7 @@ const macKeychainAdapter: GoogleCredentialStoreAdapter = {
       return undefined;
     }
   },
-  write(service, refreshToken) {
+  write(service, value, kind = 'refresh-token') {
     if (process.platform !== 'darwin') {
       throw new Error('GOOGLE_CREDENTIAL_STORE_UNAVAILABLE: macOS Keychain is required for local OAuth credential persistence');
     }
@@ -44,8 +52,8 @@ const macKeychainAdapter: GoogleCredentialStoreAdapter = {
       'add-generic-password',
       '-U',
       '-s', keychainService(service),
-      '-a', KEYCHAIN_ACCOUNT,
-      '-w', refreshToken,
+      '-a', KEYCHAIN_ACCOUNT[kind],
+      '-w', value,
     ], {
       encoding: 'utf-8',
       stdio: ['ignore', 'ignore', 'pipe'],
@@ -67,29 +75,76 @@ export function googleCredentialStoreStatus(): Record<string, unknown> {
     available: adapter.available(),
     repositoryPersistence: false,
     controllerStatePersistence: false,
+    credentialKinds: ['refresh-token', 'client-secret'],
   };
 }
 
-export function readStoredGoogleRefreshToken(service: StoredGoogleService): { token: string; source: string } | undefined {
+function readStoredGoogleCredential(
+  service: StoredGoogleService,
+  kind: StoredGoogleCredentialKind,
+): { value: string; source: string } | undefined {
   const candidates: StoredGoogleService[] = service === 'google-workspace'
     ? ['google-workspace']
     : [service, 'google-workspace'];
   for (const candidate of candidates) {
-    const cached = memoryCache.get(candidate);
-    if (cached) return { token: cached, source: `keychain:${candidate}` };
+    const key = cacheKey(candidate, kind);
+    const cached = memoryCache.get(key);
+    if (cached) return { value: cached, source: `keychain:${candidate}:${kind}` };
     if (!adapter.available()) continue;
-    const token = adapter.read(candidate)?.trim();
-    if (!token) continue;
-    memoryCache.set(candidate, token);
-    return { token, source: `keychain:${candidate}` };
+    const value = adapter.read(candidate, kind)?.trim();
+    if (!value) continue;
+    memoryCache.set(key, value);
+    return { value, source: `keychain:${candidate}:${kind}` };
   }
   return undefined;
 }
 
-export function writeStoredGoogleRefreshToken(service: StoredGoogleService, refreshToken: string): void {
-  const token = refreshToken.trim();
-  if (!token) throw new Error('GOOGLE_REFRESH_TOKEN_REQUIRED');
+function writeStoredGoogleCredential(service: StoredGoogleService, kind: StoredGoogleCredentialKind, value: string): void {
+  const normalized = value.trim();
+  if (!normalized) throw new Error(kind === 'refresh-token' ? 'GOOGLE_REFRESH_TOKEN_REQUIRED' : 'GOOGLE_CLIENT_SECRET_REQUIRED');
   if (!adapter.available()) throw new Error('GOOGLE_CREDENTIAL_STORE_UNAVAILABLE');
-  adapter.write(service, token);
-  memoryCache.set(service, token);
+  adapter.write(service, normalized, kind);
+  memoryCache.set(cacheKey(service, kind), normalized);
+}
+
+export function readStoredGoogleRefreshToken(service: StoredGoogleService): { token: string; source: string } | undefined {
+  const stored = readStoredGoogleCredential(service, 'refresh-token');
+  return stored ? { token: stored.value, source: stored.source } : undefined;
+}
+
+export function writeStoredGoogleRefreshToken(service: StoredGoogleService, refreshToken: string): void {
+  writeStoredGoogleCredential(service, 'refresh-token', refreshToken);
+}
+
+export function readStoredGoogleClientSecret(service: StoredGoogleService): { secret: string; source: string } | undefined {
+  const stored = readStoredGoogleCredential(service, 'client-secret');
+  return stored ? { secret: stored.value, source: stored.source } : undefined;
+}
+
+export function writeStoredGoogleClientSecret(service: StoredGoogleService, clientSecret: string): void {
+  writeStoredGoogleCredential(service, 'client-secret', clientSecret);
+}
+
+export function importStoredGoogleClientSecretFromClipboard(service: StoredGoogleService): Record<string, unknown> {
+  if (process.platform !== 'darwin' || !adapter.available()) throw new Error('GOOGLE_CREDENTIAL_STORE_UNAVAILABLE');
+  const secret = execFileSync('/usr/bin/pbpaste', [], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 2_000,
+  }).trim();
+  if (!secret || secret.length > 1024 || /\s/.test(secret)) throw new Error('GOOGLE_CLIENT_SECRET_CLIPBOARD_INVALID');
+  writeStoredGoogleClientSecret(service, secret);
+  execFileSync('/usr/bin/pbcopy', [], {
+    encoding: 'utf-8',
+    input: '',
+    stdio: ['pipe', 'ignore', 'ignore'],
+    timeout: 2_000,
+  });
+  return {
+    stored: true,
+    service,
+    backend: 'macos-keychain',
+    clipboardCleared: true,
+    credentialMaterialReturned: false,
+  };
 }

package/src/runtime/safe-tooling/google-oauth-broker.ts

@@ -5,6 +5,7 @@ import { URLSearchParams } from 'url';
 import { installGoogleAccessToken } from '../plugins/google-shared';
 import {
   googleCredentialStoreStatus,
+  readStoredGoogleClientSecret,
   type StoredGoogleService,
   writeStoredGoogleRefreshToken,
 } from './google-credential-store';
@@ -138,16 +139,33 @@ function base64Url(value: Buffer): string {
   return value.toString('base64url');
 }
 
-function clientId(): string | undefined {
-  return process.env.FORGE_GOOGLE_WORKSPACE_CLIENT_ID?.trim()
+function clientId(service: GoogleOAuthService): string | undefined {
+  const serviceSpecific = service === 'gmail'
+    ? process.env.FORGE_GMAIL_CLIENT_ID?.trim()
+    : service === 'calendar'
+      ? process.env.FORGE_GOOGLE_CALENDAR_CLIENT_ID?.trim()
+      : service === 'tasks'
+        ? process.env.FORGE_GOOGLE_TASKS_CLIENT_ID?.trim()
+        : undefined;
+  return serviceSpecific
+    || process.env.FORGE_GOOGLE_WORKSPACE_CLIENT_ID?.trim()
     || process.env.FORGE_GOOGLE_CLIENT_ID?.trim()
     || process.env.GOOGLE_CLIENT_ID?.trim();
 }
 
-function clientSecret(): string | undefined {
-  return process.env.FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET?.trim()
+function clientSecret(service: GoogleOAuthService): string | undefined {
+  const serviceSpecific = service === 'gmail'
+    ? process.env.FORGE_GMAIL_CLIENT_SECRET?.trim()
+    : service === 'calendar'
+      ? process.env.FORGE_GOOGLE_CALENDAR_CLIENT_SECRET?.trim()
+      : service === 'tasks'
+        ? process.env.FORGE_GOOGLE_TASKS_CLIENT_SECRET?.trim()
+        : undefined;
+  return serviceSpecific
+    || process.env.FORGE_GOOGLE_WORKSPACE_CLIENT_SECRET?.trim()
     || process.env.FORGE_GOOGLE_CLIENT_SECRET?.trim()
-    || process.env.GOOGLE_CLIENT_SECRET?.trim();
+    || process.env.GOOGLE_CLIENT_SECRET?.trim()
+    || readStoredGoogleClientSecret(service)?.secret;
 }
 
 export function prepareGoogleOAuthLogin(
@@ -157,7 +175,7 @@ export function prepareGoogleOAuthLogin(
   pruneOAuthRequests(controllerHome);
   const redirectUri = validateRedirectUri(input.redirectUri);
   const scopes = validateScopes(input.service, input.scopes);
-  const configuredClientId = clientId();
+  const configuredClientId = clientId(input.service);
   if (!configuredClientId) {
     return {
       schemaVersion: 1,
@@ -236,7 +254,7 @@ export async function completeGoogleOAuthLogin(
   }
   const code = input.code?.trim();
   if (!code) throw new Error('GOOGLE_OAUTH_CODE_REQUIRED');
-  const configuredSecret = clientSecret();
+  const configuredSecret = clientSecret(selected.record.service);
   if (!configuredSecret) throw new Error('GOOGLE_OAUTH_CLIENT_SECRET_REQUIRED');
   const body = new URLSearchParams({
     grant_type: 'authorization_code',

package/src/runtime/safe-tooling/workspace-auth.ts

@@ -88,10 +88,10 @@ export function prepareWorkspaceAuthLogin(
   controllerHomeOrInput: string | WorkspaceAuthLoginInput = {},
   maybeInput: WorkspaceAuthLoginInput = {},
 ): Record<string, unknown> {
-  bootstrapManagedRuntimeEnv();
   const controllerHome = typeof controllerHomeOrInput === 'string'
     ? controllerHomeOrInput
     : process.env.FORGE_CONTROLLER_HOME?.trim() || process.cwd();
+  bootstrapManagedRuntimeEnv({ controllerHome });
   const input = typeof controllerHomeOrInput === 'string' ? maybeInput : controllerHomeOrInput;
   const service = normalizeService(input.service);
   const redirectUri = input.redirectUri || process.env.FORGE_GOOGLE_REDIRECT_URI || 'http://127.0.0.1:8766/oauth/google/callback';

package/src/runtime/shared/bounded-child-supervisor.ts

@@ -39,6 +39,8 @@ export interface BoundedChildRunOptions {
   env?: NodeJS.ProcessEnv;
   timeoutMs: number;
   maxOutputBytes?: number;
+  /** Optional bounded stdin payload for request/response sidecars. */
+  input?: string | Buffer;
   stdio?: 'capture' | 'inherit';
   forwardSignals?: boolean;
   onSpawn?: (pid: number) => void;
@@ -120,7 +122,7 @@ export async function runBoundedChild(
   const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
   const stdio: StdioOptions = options.stdio === 'inherit'
     ? ['ignore', 'inherit', 'inherit']
-    : ['ignore', 'pipe', 'pipe'];
+    : [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'];
   let child: ChildProcess;
   try {
     child = spawn(command, [...args], {
@@ -147,6 +149,12 @@ export async function runBoundedChild(
 
   const pid = child.pid;
   if (pid) options.onSpawn?.(pid);
+  if (options.input !== undefined && child.stdin) {
+    // A canary or validation failure may close stdin before the parent writes.
+    // The child outcome is authoritative; a late EPIPE must not crash the host.
+    child.stdin.on('error', () => undefined);
+    child.stdin.end(options.input);
+  }
   let stdout = '';
   let stderr = '';
   child.stdout?.on('data', (chunk) => { stdout = appendBounded(stdout, chunk, maxOutputBytes); });