@milpa/comal 0.1.5 → 0.1.7

package/README.md

@@ -10,7 +10,7 @@ The `@milpa/comal` package includes its JavaScript dependencies; it has no insta
 npx @milpa/comal
 ```
 
-An interactive first start opens setup inside the TUI. Press Enter to try the offline demo, choose Codex to authorize the subscription in your browser, or enter an OpenAI-compatible endpoint and let Comal discover its model. A failed connection returns to setup in the same terminal. Successful connection routing is remembered in `~/.config/comal/connection.json` (or `$XDG_CONFIG_HOME/comal/connection.json`); keys are never stored there. Explicit flags, environment settings, profiles and resumed sessions take precedence. Noninteractive invocations retain plain output.
+An interactive start reuses saved routing. If routing was never saved but exactly one Comal provider login exists, Comal reconnects with that login and opens the composer. Renewable authorization uses the existing refresh flow. Multiple saved logins show a connection choice. Guided first-run setup appears when no prior connection is available. Press Enter to try the offline demo, choose Codex to authorize the subscription in your browser, or enter an OpenAI-compatible endpoint and let Comal discover its model. A failed connection returns to setup in the same terminal. Successful connection routing is remembered in `~/.config/comal/connection.json` (or `$XDG_CONFIG_HOME/comal/connection.json`); keys are never stored there. Explicit flags, environment settings, profiles and resumed sessions take precedence. Noninteractive invocations retain plain output.
 
 npm keeps its cache; Comal's state and credentials remain in your workspace and your configuration, outside that cache. No repository checkout is required.
 
@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.1.5` or `npm install --global @milpa/comal@0.1.5`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.1.7` or `npm install --global @milpa/comal@0.1.7`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 

package/backend/contracts/remote-workspace-v1.schema.json

@@ -0,0 +1,287 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "scope": {
+      "const": "recorded_work_execution"
+    },
+    "asked": {
+      "const": "unjudged"
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "row": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sha256": {
+          "type": "string",
+          "maxLength": 64,
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "integrity": {
+          "enum": [
+            "verified_hash_chain",
+            "legacy",
+            "invalid"
+          ]
+        }
+      },
+      "required": [
+        "session_id",
+        "row",
+        "sha256",
+        "integrity"
+      ]
+    },
+    "plan": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "version": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "objective": {
+              "type": "string",
+              "maxLength": 1000
+            }
+          },
+          "required": [
+            "version",
+            "objective"
+          ]
+        }
+      ]
+    },
+    "counts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pending": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "in_progress": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "blocked": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "done": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "needs_verification": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "required": [
+        "pending",
+        "in_progress",
+        "blocked",
+        "done",
+        "needs_verification"
+      ]
+    },
+    "tasks_total": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "tasks": {
+      "type": "array",
+      "maxItems": 24,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "maxLength": 64,
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 180
+          },
+          "criterion": {
+            "type": "string",
+            "maxLength": 400
+          },
+          "status": {
+            "enum": [
+              "pending",
+              "in_progress",
+              "blocked",
+              "done",
+              "needs_verification"
+            ]
+          },
+          "declared_status": {
+            "enum": [
+              "pending",
+              "in_progress",
+              "blocked",
+              "done",
+              "needs_verification"
+            ]
+          },
+          "phase": {
+            "enum": [
+              "discovery",
+              "implementation",
+              "verification"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "maxLength": 240
+          },
+          "held_by": {
+            "type": "array",
+            "maxItems": 24,
+            "items": {
+              "type": "string",
+              "maxLength": 64,
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
+            }
+          },
+          "checks_total": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "checks": {
+            "type": "array",
+            "maxItems": 4,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "step_id": {
+                  "type": "string",
+                  "maxLength": 64,
+                  "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$"
+                },
+                "operation": {
+                  "type": "string",
+                  "maxLength": 128
+                },
+                "status": {
+                  "enum": [
+                    "pending",
+                    "running",
+                    "failed",
+                    "refused",
+                    "interrupted",
+                    "not_dispatched",
+                    "stale",
+                    "passed"
+                  ]
+                },
+                "receipt_id": {
+                  "type": "string",
+                  "maxLength": 36,
+                  "pattern": "^[a-f0-9-]{36}$"
+                },
+                "receipt_row": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "required": [
+                "step_id",
+                "operation",
+                "status"
+              ],
+              "dependentRequired": {
+                "receipt_id": [
+                  "receipt_row"
+                ],
+                "receipt_row": [
+                  "receipt_id"
+                ]
+              }
+            }
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "criterion",
+          "status",
+          "declared_status",
+          "phase",
+          "reason",
+          "held_by",
+          "checks_total",
+          "checks"
+        ]
+      }
+    },
+    "receipts": {
+      "type": "array",
+      "maxItems": 8,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "maxLength": 36,
+            "pattern": "^[a-f0-9-]{36}$"
+          },
+          "operation": {
+            "type": "string",
+            "maxLength": 128
+          },
+          "status": {
+            "enum": [
+              "returned",
+              "failed",
+              "refused"
+            ]
+          },
+          "row": {
+            "type": "integer",
+            "minimum": 0
+          }
+        },
+        "required": [
+          "id",
+          "operation",
+          "status",
+          "row"
+        ]
+      }
+    }
+  },
+  "required": [
+    "version",
+    "scope",
+    "asked",
+    "source",
+    "plan",
+    "counts",
+    "tasks_total",
+    "tasks",
+    "receipts"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,
@@ -22,6 +22,7 @@
     "backend/verifier/transport.mjs",
     "backend/contracts/artifact-check-v1.schema.json",
     "backend/contracts/remote-commands-v1.json",
+    "backend/contracts/remote-workspace-v1.schema.json",
     "governance/chrome-task-v1.json",
     "governance/chrome-task-v2.json",
     "docs",

package/src/cli.mjs

@@ -4,7 +4,7 @@ registerMessages(cliSpanish);
 import { RemoteHost } from './remote-control.mjs';
 import { remoteCommandHelp, isRemoteCommand } from './remote-commands.mjs';
 import { codeRunDefinition } from './code-run.mjs';
-import { hasProviderSelection, loadConnection, onboard } from './onboarding.mjs';
+import { hasProviderSelection, loadConnection, saveConnection, existingLoginConnection, onboard } from './onboarding.mjs';
 import { stageImage, descriptorForStage, persistHumanImage } from './image-attachments.mjs';
 import { artifactPlugin } from './artifact-tools.mjs';
 import { CloudClient, publishArtifact } from './cloud-client.mjs';
@@ -37,6 +37,7 @@ import { Operation } from './operations.mjs';
 import { validateConnectionCandidate } from './connection-validation.mjs';
 import { PluginRuntime, parsePluginCommand } from './plugins.mjs';
 import { registerWorkOperations, workProjection } from './work-plan.mjs';
+import { projectRemoteWorkspace } from './remote-workspace.mjs';
 import { evidenceOperations } from './work-state.mjs';
 import { auditExecution, auditReport } from './audit.mjs';
 import { comalEnvironment } from './compat.mjs';
@@ -173,10 +174,15 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   const timing = modelTimingSettings({ timeoutMs: v['model-timeout-ms'], idleTimeoutMs: v['model-idle-timeout-ms'] });
   const chooseSettings = current => sessionProviderSettings({current, profiles, options:v, maxTokens:contextConfig.maxTokens});
   const explicitConnection = hasProviderSelection(v, profiles);
-  let savedConnection;
+  let savedConnection, recoveredLogin, knownLogins = [];
   if (!explicitConnection) {
-    try { savedConnection = await loadConnection(); if (savedConnection) Object.assign(v, savedConnection); }
+    try { savedConnection = await loadConnection(); }
     catch (error) { stderr.write(t('Saved connection could not be loaded: ') + error.message + '\n'); }
+    if (!savedConnection && !print) {
+      const existing = await existingLoginConnection(authManager); knownLogins = existing.logins;
+      recoveredLogin = existing.connection; savedConnection = recoveredLogin;
+    }
+    if (savedConnection) Object.assign(v, savedConnection);
   }
   let settings;
   try { settings = v.demo ? { provider: 'openai' } : chooseSettings(session); }
@@ -236,11 +242,17 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   };
   let connected;
   if (ui && !explicitConnection && !savedConnection) {
-    const result = await onboard({ ui, profiles, authManager, connect, signal: startupSignal });
+    const result = await onboard({ ui, profiles, authManager, connect, signal: startupSignal, logins: knownLogins });
     if (!result) return;
     Object.assign(v, result.options); connected = result.connection;
   } else if (!v.demo) {
-    try { connected = await connect({}); }
+    try {
+      connected = await connect({});
+      if (recoveredLogin) {
+        try { await saveConnection({...recoveredLogin, model: connected.provider.model}); }
+        catch (error) { ui?.notice(t('Connected, but settings could not be saved: ') + error.message, true); }
+      }
+    }
     catch (error) {
       if (!ui || startupSignal.aborted) throw error;
       const action = await ui.setupChoice({ title: t('Connection not ready'), description: error.message, signal: startupSignal, items: [
@@ -248,7 +260,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
         { id: 'exit', label: t('Exit'), description: t('Keep your saved settings.') },
       ] });
       if (action !== 'setup') return;
-      const result = await onboard({ ui, profiles, authManager, connect: options => connect(options), signal: startupSignal });
+      const result = await onboard({ ui, profiles, authManager, connect: options => connect(options), signal: startupSignal, logins: knownLogins });
       if (!result) return;
       // A new choice replaces the failed selector rather than mixing endpoints.
       for (const key of ['provider','base-url','model','profile','auth-provider']) delete v[key];
@@ -328,7 +340,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
       stderr.write(color('90', t("Session {v0} · {v1} calls · {v2} tokens", {v0: event.session_id, v1: event.turns, v2: event.usage.input_tokens + event.usage.output_tokens})) + '\n');
     }
   };
-  const house = new House({ cwd, record: event => store.append(event.session_id, event) });
+  const house = new House({ cwd, record: async event => { const row=await store.append(event.session_id,event); if(event.session_id===session.id)remoteHost?.invalidateWorkspace(); return row; } });
   if (v.codemode) house.registry.add(codeRunDefinition);
   house.guard('peer-authority',view=>peerGuard.check(view));
   const onPermission = decision => store.append(session.id, { type: 'permission', ...decision });
@@ -451,7 +463,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal) {
   house.registry.add({name:'CloudAccountLogout',description:'Human detaches Remote Control and removes the local Comal account credential.',input_schema:emptyInput,audience:'human',surfaces:['tui'],permission:null,effects:{workspace:'none',external:'write',process:'none',authority:'credential_control'},run:async()=>{await remoteHost?.stop();return cloudClient.logout();}});
   const openRemoteControl=async()=>{
     if(!runtime)throw Error('Remote Control requires an interactive local session.');
-    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text)});
+    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text),getWorkspace:async snapshot=>projectRemoteWorkspace(snapshot || await store.load(session.id),house.stateContext())});
     const connection = new AbortController(); authController = connection;
     const cancel = () => remoteHost.stop().catch(() => {});
     connection.signal.addEventListener('abort', cancel, { once: true });

package/src/i18n/es.mjs

@@ -309,5 +309,13 @@ export default Object.freeze({
   "Esc back": "Esc vuelve",
   "Working…": "Trabajando…",
   "Checking…": "Comprobando…",
-  "The draft changed while preparing the image. Press Enter again to send the current draft.": "El borrador cambió mientras se preparaba la imagen. Pulsa Enter de nuevo para enviar el borrador actual."
+  "The draft changed while preparing the image. Press Enter again to send the current draft.": "El borrador cambió mientras se preparaba la imagen. Pulsa Enter de nuevo para enviar el borrador actual.",
+  "Saved logins found. Choose the provider for this session.": "Se encontraron logins guardados. Elige el proveedor para esta sesión.",
+  "Use your saved login. No new browser authorization is needed.": "Usa tu login guardado. No necesitas otra autorización en el navegador.",
+  "This login expired. Sign in again to reconnect.": "Este login caducó. Inicia sesión otra vez para reconectar.",
+  "Connecting {provider}": "Conectando {provider}",
+  "Authorize {provider}": "Autoriza {provider}",
+  "Sign in again to {provider}": "Vuelve a iniciar sesión con {provider}",
+  "Start a new sign-in only if you choose this option.": "Inicia otra autenticación solo si eliges esta opción."
+
 });

package/src/onboarding.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { t } from './i18n/index.mjs';
+import { AUTH_PROVIDERS } from './provider-auth.mjs';
 
 const selectors = ['provider', 'base-url', 'model', 'profile', 'providers-config', 'auth-provider'];
 export function hasProviderSelection(options = {}, profiles = {}, env = process.env) {
@@ -32,35 +33,57 @@ export async function saveConnection(value, { env = process.env } = {}) {
   finally { await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; }); }
 }
 
+// Local status only: never starts OAuth or imports credentials from another CLI.
+// Authorization can predate connection.json. Multiple known logins are a choice,
+// even if only one is currently usable; do not guess which account is intended.
+export async function existingLoginConnection(authManager) {
+  const results = await Promise.allSettled(AUTH_PROVIDERS.map(provider => authManager.status(provider.id)));
+  const logins = results.flatMap((result, index) => {
+    if (result.status !== 'fulfilled' || !['authenticated', 'configured', 'expired'].includes(result.value?.status)) return [];
+    const {status, canRefresh} = result.value;
+    return [{id: AUTH_PROVIDERS[index].id, label: AUTH_PROVIDERS[index].label,
+      usable: status !== 'expired' || canRefresh === true}];
+  });
+  return {logins, connection: logins.length === 1 && logins[0].usable ? {'auth-provider': logins[0].id} : null};
+}
+
 // The terminal stays owned by the caller. Only a successfully validated connection
 // is remembered; credentials live in AuthManager/environment, never in this file.
-export async function onboard({ ui, profiles, authManager, connect, signal, env = process.env }) {
+export async function onboard({ ui, profiles, authManager, connect, signal, env = process.env, logins = [] }) {
   while (!signal?.aborted && !ui.closed) {
-    const choice = await ui.setupChoice({ title: t('Your first turn'), description: t('Choose how to start. Stay here while Comal connects.'), signal, items: [
-      { id: 'demo', label: t('Try the offline demo'), description: t('No account or model. A scripted tool cycle; no inference.') },
+    const returning = logins.length > 0;
+    const demo = {id: 'demo', label: t('Try the offline demo'), description: t('No account or model. A scripted tool cycle; no inference.')};
+    const choice = await ui.setupChoice({ title: t(returning ? 'Choose a connection' : 'Your first turn'), description: t(returning ? 'Saved logins found. Choose the provider for this session.' : 'Choose how to start. Stay here while Comal connects.'), signal, items: [
+      ...(!returning ? [demo] : []),
+      ...logins.map(login => ({id: 'saved:' + login.id, label: login.label, description: t(login.usable ? 'Use your saved login. No new browser authorization is needed.' : 'This login expired. Sign in again to reconnect.')})),
+      ...logins.filter(login => login.usable).map(login => ({id: 'login:' + login.id, label: t('Sign in again to {provider}', {provider: login.label}), description: t('Start a new sign-in only if you choose this option.')})),
       ...profiles.profiles.map(profile => ({ id: 'profile:' + profile.name, label: profile.name, description: `${profile.provider} · ${profile.model || t('discover model')}` })),
-      { id: 'codex', label: t('Connect Codex'), description: t('Sign in with your existing subscription in the browser.') },
+      ...(!logins.some(login => login.id === 'codex') ? [{ id: 'codex', label: t('Connect Codex'), description: t('Sign in with your existing subscription in the browser.') }] : []),
       { id: 'server', label: t('Connect a model server'), description: t('OpenAI-compatible endpoint. API keys stay in your environment.') },
+      ...(returning ? [demo] : []),
     ] });
     if (!choice || signal?.aborted || ui.closed) return null;
     if (choice === 'demo') { ui.clearSetup(); return { options: { demo: true } }; }
     let options;
     try {
       if (choice.startsWith('profile:')) options = { profile: choice.slice(8) };
-      else if (choice === 'codex') {
-        ui.setupStatus({ title: t('Connecting Codex'), description: t('Waiting for browser authorization. Esc cancels this connection.') });
+      else if (choice.startsWith('saved:') && logins.some(login => 'saved:' + login.id === choice && login.usable)) options = {'auth-provider': choice.slice(6)};
+      else if (choice === 'codex' || choice.startsWith('saved:') || choice.startsWith('login:')) {
+        const target = choice === 'codex' ? 'codex' : logins.find(login => ['saved:' + login.id, 'login:' + login.id].includes(choice))?.id;
+        if (!target) throw Error('Unknown saved login.');
+        ui.setupStatus({ title: target === 'codex' ? t('Connecting Codex') : t('Connecting {provider}', {provider: target}), description: t('Waiting for browser authorization. Esc cancels this connection.') });
         const operation = new AbortController();
         ui.callbacks.onSetupCancel = () => operation.abort();
         try {
-          const status = await authManager.status('codex');
+          const status = await authManager.status(target);
           operation.signal.throwIfAborted(); signal?.throwIfAborted();
-          if (status.status !== 'authenticated') await authManager.login('codex', { signal: signal ? AbortSignal.any([signal, operation.signal]) : operation.signal, onEvent: event => {
+          if (choice.startsWith('login:') || !['authenticated', 'configured'].includes(status.status)) await authManager.login(target, { signal: signal ? AbortSignal.any([signal, operation.signal]) : operation.signal, onEvent: event => {
             if (operation.signal.aborted || signal?.aborted || ui.closed) return;
-            if (event.type === 'device_code') ui.setupStatus({ title: t('Authorize Codex'), description: `${event.verification_uri}\n\n${t('Code')}: ${event.user_code}\n\n${t('Approve only if you started this connection. Esc cancels.')}` });
+            if (event.type === 'device_code') ui.setupStatus({ title: target === 'codex' ? t('Authorize Codex') : t('Authorize {provider}', {provider: target}), description: `${event.verification_uri}\n\n${t('Code')}: ${event.user_code}\n\n${t('Approve only if you started this connection. Esc cancels.')}` });
           } });
           operation.signal.throwIfAborted(); signal?.throwIfAborted();
         } finally { delete ui.callbacks.onSetupCancel; }
-        options = { 'auth-provider': 'codex' };
+        options = { 'auth-provider': target };
       } else {
         const endpoint = await ui.setupInput({ title: t('Model server'), description: t('Endpoint URL. No API key or password in the URL.'), value: 'http://127.0.0.1:8080/v1', signal, validate: text => { try { normalizeConnection({ provider: 'openai', 'base-url': text }); return true; } catch (error) { return error.message; } } });
         if (!endpoint) continue;

package/src/provider-auth.mjs

@@ -99,6 +99,7 @@ export class AuthManager {
     const p = definition(name), record = await this._read(p.id);
     return { provider: p.id, method: record?.method || p.method, subscription: p.subscription,
       status: !record ? 'logged_out' : record.expiresAt && record.expiresAt <= this.now() ? 'expired' : record.method === 'device_code' ? 'authenticated' : 'configured',
+      ...(record?.method === 'device_code' ? {canRefresh: secret(record.refreshToken)} : {}),
       ...(record?.expiresAt ? { expiresAt: record.expiresAt } : {}),
       ...(p.apiKeyEnv ? { apiKeyEnv: p.apiKeyEnv } : {}), documentation: p.documentation,
       ...(p.experimental ? { experimental: true, note: 'OAuth compatible with the public Kimi CLI code; the documented route for external clients is a Kimi Code key (--api-key-env KIMI_CODE_API_KEY).' } : {}),

package/src/remote-control.mjs

@@ -26,8 +26,8 @@ const cancelled = () => Object.assign(new Error('Remote Control connection cance
 const lifetimeSignal = (run,timeout=10000) => run?.controller ? AbortSignal.any([run.controller.signal,AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout);
 
 export class RemoteHost {
-  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
-    Object.assign(this,{client,onInput,onStop,onNotice,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
   }
   status(){return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only'}:{enabled:false};}
   current(run,{starting=false}={}) {return this.lifecycle===run && (starting || !this.stopped) && !run?.controller?.signal.aborted;}
@@ -48,7 +48,8 @@ export class RemoteHost {
         const account=await this.client.credentials();this.assertCurrent(run,{starting:true});
         if(!account)throw Error('Sign in with comal cloud login before enabling Remote Control.');
         run.account={origin:account.origin,user_id:account.user_id};run.enablingToken=account.token;
-        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1']},{expectedAccount:run.account,signal:run.controller.signal});
+        const workspace=this.getWorkspace?await this.getWorkspace(session):null;this.assertCurrent(run,{starting:true});
+        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[])]},{expectedAccount:run.account,signal:run.controller.signal});
         run.session=opened.session;
         // Abort can race a successful response. Revoke a late-created grant even
         // when the local stop completed before its identifier became available.
@@ -56,6 +57,7 @@ export class RemoteHost {
         this.account=run.account;this.enablingToken=run.enablingToken;this.session=opened.session;this.url=opened.url;this.stopped=false;
         await this.authorize(run);this.assertCurrent(run);await this.pulse(run);this.assertCurrent(run);
         this.transport='https-polling';this.connectSocket(run);
+        if(workspace)this.publishWorkspace(workspace,run);
         this.timer=setInterval(()=>this.tick(run),1000);this.timer.unref();
         for(const message of (session.historyMessages || []).slice(-20)){
           const event=message.role==='user'&&(typeof message.content==='string'||Array.isArray(message.content)&&message.content.some(block=>block.type==='text'))?{type:'user',text:typeof message.content==='string'?message.content:message.content.filter(block=>block.type==='text').map(block=>block.text).join('\n')}:message.role==='assistant'?{type:'assistant',message}:null;
@@ -103,8 +105,30 @@ export class RemoteHost {
     }catch{/* HTTPS is already active. A later tick retries WSS. */}
     finally{if(this.connecting===marker){this.connecting=null;if(this.current(run))this.nextSocketAt=Date.now()+10000;}}
   }
+  publishWorkspace(workspace,run=this.lifecycle) {
+    if(!this.current(run))return;
+    const {source,...content}=workspace,key=digest(content);
+    if(run.workspaceDigest===key)return;
+    if(this.pending.length>=512)throw Error('Remote workspace buffer full.');
+    this.pending.push({event_id:randomUUID(),event:{type:'workspace.snapshot',text:'',turn_id:this.turnId||'local',workspace}});
+    run.workspaceDigest=key;this.flush(run).catch(()=>{});
+  }
+  invalidateWorkspace() {
+    const run=this.lifecycle;if(!this.current(run)||!this.getWorkspace)return;
+    run.workspaceDirty=true;
+    if(run.workspaceTimer||run.workspaceLoading)return;
+    run.workspaceTimer=setTimeout(()=>{run.workspaceTimer=null;this.refreshWorkspace(run);},750);run.workspaceTimer.unref();
+  }
+  async refreshWorkspace(run=this.lifecycle) {
+    if(!this.current(run)||!this.getWorkspace||run.workspaceLoading)return;
+    run.workspaceLoading=true;run.workspaceDirty=false;
+    try {const workspace=await this.getWorkspace();if(this.current(run))this.publishWorkspace(workspace,run);}
+    catch {if(this.current(run))this.onNotice('Remote work state unavailable; local execution continues.');}
+    finally {run.workspaceLoading=false;if(this.current(run)&&run.workspaceDirty)this.invalidateWorkspace();}
+  }
   observe(event) {
     if(this.stopped)return;
+    if(['tool_result','house_waiting','house_answered','result'].includes(event.type))this.invalidateWorkspace();
     const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
     if(event.type==='model_stream_progress'&&event.reasoning_chars>0&&!this.thinkingActive){
       this.thinkingActive=true;append({type:'thinking.started',turn_id:this.turnId||'local',text:'Thinking…'});this.flush().catch(()=>{});return;
@@ -139,6 +163,7 @@ export class RemoteHost {
   pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(this.current(run))return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId},run);});this.pulsing=work;return work;}
   async beginTurn(){this.turnId=randomUUID();if(!this.stopped)this.pulse().catch(error=>{if(error.code!=='REMOTE_CANCELLED')this.onNotice('Remote state unavailable: '+error.message);});}
   async endTurn(){
+    this.invalidateWorkspace();
     if(!this.stopped){this.pending.push({event_id:randomUUID(),event:{type:'turn.settled',text:'Local turn settled.',turn_id:this.turnId || 'local'}});this.flush().catch(()=>{});}
     clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';this.thinkingActive=false;this.turnId=null;this.pulse().catch(()=>{});
   }
@@ -172,7 +197,7 @@ export class RemoteHost {
   }
   async stop(){
     const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
-    this.lifecycle=null;this.starting=null;run.controller?.abort();
+    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);
     this.stopped=true;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
     this.access=null;this.enablingToken=null;this.pending=[];this.turnId=null;this.processing=null;this.sending=null;this.pulsing=null;this.connecting=null;
     await this.revoke(run);return this.status();

package/src/remote-workspace.mjs

@@ -0,0 +1,50 @@
+import { foldWorkBook } from './work-plan.mjs';
+import { auditJournal } from './audit.mjs';
+
+const text = (value, bytes) => Buffer.from(String(value ?? '')).subarray(0, bytes).toString('utf8').replace(/\uFFFD$/, '');
+const reasons = {
+  'Una comprobación perdió vigencia en el libro.':'A recorded check is no longer current.',
+  'La evidencia de una dependencia cambió; vuelve a comprobar esta tarea.':'Dependency evidence changed; verify this task again.',
+  'Una dependencia perdió su cierre vigente.':'A dependency no longer has current completion evidence.',
+  'Espera una respuesta humana.':'Waiting for an answer in the local terminal.',
+};
+const states = new Set(['pending', 'in_progress', 'blocked', 'done', 'needs_verification']);
+const checkStates = new Set(['running', 'failed', 'refused', 'interrupted', 'not_dispatched']);
+
+/** Host projection only: no arguments, assertions, file contents, drafts or raw outputs. */
+export function projectRemoteWorkspace(session, context = {}) {
+  const rows = session.rows || [], journal = auditJournal(rows), book = foldWorkBook(session, context);
+  const counts = Object.fromEntries([...states].map(status => [status, book.tasks.filter(task => task.status === status).length]));
+  const tasks = [...book.tasks].sort((a, b) => ['in_progress', 'blocked', 'needs_verification', 'pending', 'done'].indexOf(a.status) - ['in_progress', 'blocked', 'needs_verification', 'pending', 'done'].indexOf(b.status)).slice(0, 24).map(task => ({
+    id: task.id, title: text(task.title, 180), criterion: text(task.criterion, 400),
+    status: journal.verified ? task.status : task.status === 'done' ? 'needs_verification' : task.status,
+    declared_status: states.has(task.declared_status) ? task.declared_status : 'pending',
+    phase: task.phase || 'implementation', reason: text(reasons[task.reason] || task.reason, 240), held_by: task.held_by.slice(0, 24),
+    checks_total: task.checks.length,
+    checks: task.checks.slice(0, 4).map(check => {
+      const step = book.steps.find(step => step.task_id === task.id && step.step_id === check.step_id);
+      const receipt = book.receipts.get(step?.receipt_id);
+      const status = journal.verified && book.checkValid(task, check, step) ? 'passed'
+        : step?.preflight_failure ? 'not_dispatched'
+        : step?.status === 'returned' ? 'stale'
+        : checkStates.has(step?.status) ? step.status : 'pending';
+      return { step_id: check.step_id, operation: text(check.operation, 128), status,
+        ...(receipt ? { receipt_id: receipt.invocation_id, receipt_row: receipt.evidence_row } : {}) };
+    }),
+  }));
+  const references = new Set([...book.steps.map(step => step.receipt_id), ...book.tasks.flatMap(task => task.receipt_ids || [])]);
+  const receipts = [...book.receipts.values()].filter(receipt => references.has(receipt.invocation_id)).slice(-8).reverse().map(receipt => ({
+    id: receipt.invocation_id, operation: text(receipt.operation, 128), status: receipt.status, row: receipt.evidence_row,
+  }));
+  if (!journal.verified) { const previousDone=counts.done; counts.done=0; counts.needs_verification+=previousDone; }
+  const result = {
+    version: 1, scope: 'recorded_work_execution', asked: 'unjudged',
+    source: { session_id: session.id, row: Math.max(0, rows.length - 1), sha256: journal.tip_sha256 || '0'.repeat(64), integrity: journal.verified ? 'verified_hash_chain' : journal.consistent ? 'legacy' : 'invalid' },
+    plan: book.plan ? { version: book.plan.version, objective: text(book.plan.objective, 1000) } : null,
+    counts, tasks_total: book.tasks.length, tasks, receipts,
+  };
+  // The stream has a 48 KiB event ceiling, including its transport envelope.
+  // Keep whole task/check records and disclose omissions through total counts.
+  while (Buffer.byteLength(JSON.stringify(result)) > 36000 && result.tasks.length) result.tasks.pop();
+  return result;
+}