@awak-app/simy-cli 0.6.11 → 0.6.12

package/README.md

@@ -816,3 +816,29 @@ Only summary metadata is retained, without analysis prompts, source inputs,
 model responses or credentials. Historical summaries are not a replacement for
 signed proof files or delivery acceptance. Records from versions that kept
 analysis only in memory cannot be recovered after that process exits.
+
+
+### Reusing a running service and launch recovery
+
+`simy` and `simy --daemon` first inspect the private discovery record and verify
+its live PID, instance, Web origin, CLI/API version and saved account,
+organization and device. A compatible background service is reused: the entry
+prints its existing address and opens SIMY Web (or its sign-in page). The local
+interactive console is only created when this entry owns a new service.
+SQM authorization also reuses that service and leaves it running when SQM exits.
+Unreachable or incompatible live services produce diagnostics instead of a
+second daemon. A stale record with a dead PID permits normal startup.
+
+Web-led launches can omit their temporary challenge. The daemon requests a
+credential for the existing queued run using its authenticated device. An
+explicitly expired challenge can be renewed once; consumed, invalid or
+cross-scope credentials cannot. Refresh the original run/device before retrying
+a consumed credential because execution may have started before its ledger
+status was uploaded. This recovery requires the companion Web
+`/api/local-cli/challenges/issue` endpoint; existing valid challenges continue
+to work against older Web versions.
+
+Scope mismatch diagnostics identify the changed account, organization, device
+or Web host and tell the caller to restore the original identity. Launch and
+recovery operations do not switch identity automatically. The private
+`/v1/connection` endpoint rejects browser requests and never returns tokens.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
     "check:workflow-observation-sender": "node --check ./src/workflow-observation-sender.js",
     "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/reliability.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./src/sqm/agent-skill.js && node --check ./src/sqm/workflow-onboarding.js && node --check ./src/sqm/workflow-update.js && node --check ./src/sqm/history-store.js && node --check ./src/sqm/review-worker.js && node --check ./scripts/sqm-complete-loop-e2e.js && node --check ./scripts/sqm-local-review-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/claude-parity-runtime-e2e.js && node --check ./scripts/claude-plugin-runtime-e2e.js",
-    "check:syntax": "node --check ./src/purpose-local-proof.js && node --check ./src/device-signing-identity.js && node --check ./src/index.js && node --check ./src/install-update.js && node --check ./src/agent.js && node --check ./src/connection-discovery.js && node --check ./src/codex-plugins/simy/hooks/connection-reminder.mjs && node --check ./src/codex-plugins/simy/hooks/dev-work.mjs && node --check ./src/dev-work-events.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/login-shell-path.js && node --check ./src/hook-runtime.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/pr-preparation.js && node --check ./src/orchestrator/minimum-completion.js && node --check ./src/orchestrator/delivery/scripts/check-minimum-completion.mjs && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./src/coding-run-store.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js && node --check ./src/codex-plugins/simy/hooks/delivery-loop.mjs && node --check ./src/delivery-hooks/command.js && node --check ./src/delivery-hooks/desktop.js && node --check ./src/delivery-hooks/supervisor.js && node --check ./src/session-supervision/automatic-continuation.js && node --check ./src/session-supervision/stop-notifications.js",
+    "check:syntax": "node --check ./src/purpose-local-proof.js && node --check ./src/device-signing-identity.js && node --check ./src/index.js && node --check ./src/install-update.js && node --check ./src/agent.js && node --check ./src/connection-discovery.js && node --check ./src/connection-diagnostics.js && node --check ./src/launch-authorization.js && node --check ./src/codex-plugins/simy/hooks/connection-reminder.mjs && node --check ./src/codex-plugins/simy/hooks/dev-work.mjs && node --check ./src/dev-work-events.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/login-shell-path.js && node --check ./src/hook-runtime.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/pr-preparation.js && node --check ./src/orchestrator/minimum-completion.js && node --check ./src/orchestrator/delivery/scripts/check-minimum-completion.mjs && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./src/coding-run-store.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js && node --check ./src/codex-plugins/simy/hooks/delivery-loop.mjs && node --check ./src/delivery-hooks/command.js && node --check ./src/delivery-hooks/desktop.js && node --check ./src/delivery-hooks/supervisor.js && node --check ./src/session-supervision/automatic-continuation.js && node --check ./src/session-supervision/stop-notifications.js",
     "check:package": "node ./scripts/check-package-contents.js",
     "build:macos-installer:dev": "bash packaging/build-macos-arm64.sh --unsigned-dev",
     "build:macos-installer": "bash packaging/build-macos-arm64.sh --production",

package/src/agent.js

@@ -1,3 +1,5 @@
+import { assertConnectionScope, connectionScope, connectionDiagnostic } from "./connection-diagnostics.js";
+import { authorizeLaunch } from "./launch-authorization.js";
 import { normalizePurposeVerification, assertPurposeActor, preparePurposeVerification, verifyPurposeLocalTask, purposeSigningKeyPath, purposeVerificationCapability, purposeWorkspaceBusy } from "./purpose-local-proof.js";
 import { startupRequirementChecks, summarizeStartupChecks } from "./startup-preflight.js";
 import { BROWSER_HANDOFF_TRANSPORT, browserHandoffPage, decryptBrowserHandoff } from "./browser-handoff.js";
@@ -540,7 +542,7 @@ export async function startAgent({
     })();
     return organizationRefresh;
   };
-  const requestDesktopLogin = (organizationId = null, { passive = false } = {}) => {
+  const requestDesktopLogin = (organizationId = null, { passive = false, reauthorize = false } = {}) => {
     const authorization = authorizationWindow.snapshot();
     if (authorization.state === "timed_out") {
       if (passive) return null;
@@ -568,7 +570,7 @@ export async function startAgent({
       refreshAvailableCapabilities();
       notifyDesktopStatusChange();
     } else if (isSessionValid(session, Date.now(), apiOrigin)) {
-      if (!enforceDesktopAccess || desktopAccess.snapshot().state !== 'signed_out') return null;
+      if (!reauthorize && (!enforceDesktopAccess || desktopAccess.snapshot().state !== 'signed_out')) return null;
       if (!passive || !loginUrl) {
         authNonce = randomBytes(16).toString("base64url");
         loginUrl = null;
@@ -1027,14 +1029,17 @@ export async function startAgent({
     );
   };
 
+  let connectionDiscovery = null;
+  const launchingRuns = new Set();
   const server = createServer(async (req, res) => {
+    let reservedLaunch = null;
     try {
       const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
       const localHandoff = url.pathname === "/v1/auth/browser-complete";
       const localOrigin = `http://127.0.0.1:${port}`;
       if (localHandoff ? (req.headers.origin !== localOrigin || req.headers.host !== `127.0.0.1:${port}`)
           : !isRequestOriginAllowed(req.headers.origin, apiOrigin)) {
-        json(res, 403, { error: "request origin does not match the configured SIMY Web host" });
+        json(res, 403, connectionDiagnostic("connection_scope_changed", "web_origin"));
         return;
       }
       applyCors(req, res, apiOrigin);
@@ -1050,7 +1055,7 @@ export async function startAgent({
         return;
       }
       const agenticLoopPath = canonicalAgenticLoopPath(url.pathname);
-      const desktopRecoveryRoute = ['/v1/health', '/v1/capabilities', '/v1/auth/complete', '/v1/auth/browser-complete'].includes(url.pathname) ||
+      const desktopRecoveryRoute = ['/v1/health', '/v1/connection', '/v1/capabilities', '/v1/auth/complete', '/v1/auth/browser-complete'].includes(url.pathname) ||
         req.method === 'POST' && (/^\/v1\/local-tasks\/[^/]+\/control$/.test(url.pathname) || /^\/v1\/agentic-loop\/[^/]+\/control$/.test(agenticLoopPath));
       let requestAccessScope;
       if (enforceDesktopAccess && !desktopRecoveryRoute) {
@@ -1075,6 +1080,28 @@ export async function startAgent({
         res.once("finish", releaseUpdateWork);
         res.once("close", releaseUpdateWork);
       }
+      if (["GET", "POST"].includes(req.method) && url.pathname === "/v1/connection") {
+        // Private local entry points only. Browser origins must not read account
+        // bindings, instance identifiers or the pending authorization nonce.
+        if (req.headers.origin !== undefined || req.headers.host !== `127.0.0.1:${port}`) {
+          json(res, 403, { error: "Local connection discovery only.", code: "local_connection_only" }); return;
+        }
+        let authorizationUrl;
+        if (req.method === "POST") {
+          const body = await readJson(req);
+          if (!connectionDiscovery?.instanceId || body.instance_id !== connectionDiscovery.instanceId) {
+            json(res, 409, connectionDiagnostic("connection_service_mismatch")); return;
+          }
+          try { assertConnectionScope(body.scope, connectionScope(session || reclaimableSession, apiOrigin)); }
+          catch (error) { json(res, 409, { error: error.message, code: error.code, field: error.field, recovery: error.recovery }); return; }
+          authorizationUrl = requestDesktopLogin(null, { reauthorize: body.reauthorize === true });
+        } else authorizationUrl = requestDesktopLogin(null, { passive: true });
+        json(res, 200, { ok: true, cli_version: CLI_VERSION, api_contract_version: CLI_API_CONTRACT_VERSION,
+          daemon, web_origin: apiOrigin, instance_id: connectionDiscovery?.instanceId || null, pid: process.pid,
+          scope: connectionScope(session || reclaimableSession, apiOrigin), session_valid: isSessionValid(session, Date.now(), apiOrigin),
+          login_url: authorizationUrl });
+        return;
+      }
       if (req.method === "GET" && url.pathname === "/v1/health") {
         const sessionValid = isSessionValid(session, Date.now(), apiOrigin);
         const connection = connectionStatus.snapshot({ authenticated: sessionValid });
@@ -1987,25 +2014,23 @@ export async function startAgent({
             return;
           }
         }
-        const verified = await verifyLaunchChallenge({
-          apiOrigin,
-          apiBaseUrl: session.api_base_url,
-          token: session.token,
-          runId: String(body.run_id || ""),
-          challenge: String(body.challenge || ""),
-        });
-        if (!verified.ok) {
-          json(res, 403, { error: verified.error || "launch challenge rejected" });
-          return;
-        }
         const runId = String(body.run_id || "");
-        if (!runId) {
-          json(res, 400, { error: "run_id is required" });
-          return;
-        }
+        if (!runId) { json(res, 400, { error: "run_id is required" }); return; }
+        const launchSession = session;
+        try { assertConnectionScope(body.connection_scope, connectionScope(launchSession, apiOrigin)); }
+        catch (error) { json(res, 409, { error: error.message, code: error.code, field: error.field, recovery: error.recovery }); return; }
+        if (launchingRuns.has(runId)) { json(res, 409, { error: "This launch is still being checked. Refresh its status before retrying.", code: "launch_in_progress" }); return; }
+        launchingRuns.add(runId);
+        reservedLaunch = runId;
+        const verified = await authorizeLaunch({ apiOrigin, apiBaseUrl: launchSession.api_base_url,
+          token: launchSession.token, runId, challenge: String(body.challenge || ""),
+          fetchImpl: dependencies.fetch || globalThis.fetch });
+        if (session !== launchSession || !isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 409, changedLaunchSession(launchSession, session, apiOrigin)); return;
+        }
+        if (!verified.ok) { json(res, verified.status, connectionDiagnostic(verified.code)); return; }
         if (registry.has(runId)) {
-          json(res, 409, { error: "agentic loop run already exists" });
-          return;
+          json(res, 409, { error: "agentic loop run already exists" }); return;
         }
         let executionTarget;
         try {
@@ -2069,6 +2094,10 @@ export async function startAgent({
           });
           return;
         }
+        if (session !== launchSession || !isSessionValid(session, Date.now(), apiOrigin)) {
+          await cleanupRunAttachments(stagedAttachments);
+          json(res, 409, changedLaunchSession(launchSession, session, apiOrigin)); return;
+        }
         const run = createRun({
           runId,
           request: {
@@ -2136,6 +2165,9 @@ export async function startAgent({
           throw error;
         }
         await authorizeDesktopWork(requestAccessScope);
+        if (session !== launchSession || !isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 409, changedLaunchSession(launchSession, session, apiOrigin)); return;
+        }
         void startLocalCodingRun(run, dependencies.runOptions);
         json(res, 202, { ok: true, run_id: run.id });
         return;
@@ -2216,7 +2248,7 @@ export async function startAgent({
             json(res, 200, { recovery, run_id: run.id, resumed: false });
           }
         } catch (error) {
-          json(res, 409, { error: error instanceof Error ? error.message : "Recovery could not be verified.", code: error.code || "recovery_rejected" });
+          json(res, 409, { error: error instanceof Error ? error.message : "Recovery could not be verified.", code: error.code || "recovery_rejected", ...(error.field ? { field: error.field, recovery: error.recovery } : {}) });
         }
         return;
       }
@@ -2449,13 +2481,16 @@ export async function startAgent({
       }
       if (String(err?.code || "").startsWith("purpose_verification_")) { json(res, err.status || 409, { error: err.message, code: err.code }); return; }
       json(res, 500, { error: err instanceof Error ? err.message : "internal error" });
+    } finally {
+      // An aborted HTTP response must not leave a permanent launch reservation.
+      // Keep the reservation until all asynchronous preparation has settled.
+      if (reservedLaunch) launchingRuns.delete(reservedLaunch);
     }
   });
 
   await new Promise((resolve) => server.listen(requestedPort, "127.0.0.1", resolve));
   const address = server.address();
   port = typeof address === "object" && address ? address.port : requestedPort;
-  let connectionDiscovery = null;
   try {
     connectionDiscovery = await (
       dependencies.publishConnectionDiscovery || publishConnectionDiscovery
@@ -3292,26 +3327,6 @@ function backendPreflightSummary(backend, inspection) {
   return `${label} is not available. Install or update it: ${inspection.update_command}`;
 }
 
-async function verifyLaunchChallenge({ apiOrigin, apiBaseUrl, token, runId, challenge }) {
-  try {
-    const response = await fetch(
-      webApiUrl("challenges/verify", { webOrigin: apiOrigin, apiBaseUrl }),
-      {
-        method: "POST",
-        headers: webApiHeaders(
-          { token },
-          { "Content-Type": "application/json" },
-        ),
-        body: JSON.stringify({ run_id: runId, challenge }),
-      },
-    );
-    if (response.ok) return { ok: true };
-    const payload = await response.json().catch(() => null);
-    return { ok: false, error: webApiErrorMessage(payload, response.status) };
-  } catch (err) {
-    return { ok: false, error: err instanceof Error ? err.message : "challenge check failed" };
-  }
-}
 
 function canonicalAgenticLoopPath(pathname) {
   return pathname.replace(/^\/v1\/coding-loop(?=\/|$)/, "/v1/agentic-loop");
@@ -3573,3 +3588,9 @@ function providerAuthenticationFailure(provider, status) {
     }),
   };
 }
+
+function changedLaunchSession(previous, current, origin) {
+  try { assertConnectionScope(connectionScope(previous, origin), connectionScope(current, origin)); }
+  catch (error) { return { error: error.message, code: error.code, field: error.field, recovery: error.recovery }; }
+  return connectionDiagnostic("connection_session_changed");
+}

package/src/cli-contract.js

@@ -13,7 +13,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.6.11";
+export const CLI_VERSION = "0.6.12";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/coding-run-recovery.js

@@ -91,6 +91,11 @@ export function assertRecoveryActor(run) {
     if (saved[field] && saved[field] !== current[field]) {
       const error = new Error(`The saved run belongs to another ${field}; restore its original authorized session.`);
       error.code = "recovery_actor_mismatch";
+      error.field = field;
+      error.recovery = { action: "reconnect_cli", steps: [
+        "Select the original SIMY Web host, account and organization.",
+        "Reconnect the original device, refresh the saved run and retry recovery.",
+      ] };
       throw error;
     }
   }

package/src/connection-diagnostics.js

@@ -0,0 +1,77 @@
+export function connectionScope(session, webOrigin) {
+  return {
+    web_origin: webOrigin,
+    account_id: session?.account_id || session?.auth_user_id || null,
+    organization_id: session?.organization_id || session?.org_id || null,
+    device_id: session?.device_id || null,
+  };
+}
+
+export function connectionDiagnostic(code, field = null) {
+  const scopeChanged = code === "connection_scope_changed";
+  const error = scopeChanged
+    ? `SIMY ${field.replaceAll("_", " ")} changed. Restore the account, organization, device and Web host that authorized this run before reconnecting.`
+    : {
+        connection_service_mismatch:
+          "The discovered port belongs to a different service. Run simy doctor, then reconnect to the original SIMY Web host.",
+        connection_service_unavailable:
+          "A SIMY service is recorded but cannot be reached. Run simy doctor; reopen SIMY or restart the confirmed daemon before reconnecting.",
+        connection_service_not_background:
+          "The existing SIMY service runs in a foreground terminal. Keep that terminal open, or stop it when idle and start simy --daemon before reconnecting.",
+        connection_port_mismatch:
+          "The existing SIMY service uses a different port. Reconnect without --port to reuse it, or select its recorded port.",
+        connection_session_changed:
+          "SIMY sign-in changed while the launch was being authorized. Refresh this run on the original device before retrying.",
+        connection_service_incompatible:
+          "The existing SIMY service has an incompatible version or API. Run simy update --check; update or restart that service when its tasks are idle.",
+        connection_session_expired:
+          "SIMY sign-in expired. Open the verification link for the existing service and sign in to the original account and organization.",
+        launch_challenge_expired:
+          "The launch credential expired. Retry this same run to obtain a fresh credential.",
+        launch_challenge_consumed:
+          "This launch credential was already used. Refresh the run status on its original device before retrying; execution may already have started.",
+        launch_scope_mismatch:
+          "This run or credential is unavailable for the current account, organization or device. Reconnect to the service and identity that authorized the run.",
+        launch_challenge_invalid:
+          "The launch credential is invalid. Refresh this run in SIMY Web and reconnect to its original device.",
+        launch_service_incompatible:
+          "SIMY Web does not support launch-credential recovery yet. Update the Web service, refresh this run and retry on its original device.",
+        launch_service_unavailable:
+          "The SIMY launch service could not be reached. Check the connection and retry this same run.",
+        launch_run_not_queued:
+          "This run has already progressed or stopped. Refresh its status on the original device before starting anything again.",
+      }[code] ||
+      "SIMY could not authorize this launch. Refresh the run in SIMY Web and reconnect to its original device.";
+  return {
+    error,
+    code,
+    ...(field ? { field } : {}),
+    recovery: {
+      action: "reconnect_cli",
+      steps:
+        scopeChanged || code === "launch_scope_mismatch"
+          ? [
+              "Select the original SIMY Web host, account and organization.",
+              "Reconnect the original device, refresh the run and retry.",
+            ]
+          : [error],
+    },
+  };
+}
+
+export function assertConnectionScope(expected, current) {
+  for (const field of [
+    "web_origin",
+    "account_id",
+    "organization_id",
+    "device_id",
+  ]) {
+    if (expected?.[field] && expected[field] !== current?.[field]) {
+      const diagnostic = connectionDiagnostic(
+        "connection_scope_changed",
+        field,
+      );
+      throw Object.assign(new Error(diagnostic.error), diagnostic);
+    }
+  }
+}

package/src/connection-discovery.js

@@ -3,6 +3,8 @@ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 
+import { assertConnectionScope, connectionDiagnostic } from "./connection-diagnostics.js";
+
 import { normalizeWebOrigin } from "./web-origin.js";
 
 export function connectionDiscoveryPath(webOrigin, sessionRoot) {
@@ -47,3 +49,162 @@ export async function removeConnectionDiscovery(discovery) {
     if (error?.code !== "ENOENT" && !(error instanceof SyntaxError)) throw error;
   }
 }
+
+// A private discovery file identifies a candidate; the live instance must prove
+// it owns that record before an entry point can reuse it. Never send a token.
+export async function findReusableConnection({
+  webOrigin,
+  sessionRoot,
+  cliVersion,
+  apiContractVersion,
+  expectedScope,
+  requestedPort = 0,
+  authorize = false,
+  reauthorize = false,
+  fetchImpl = fetch,
+  alive = (pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+}) {
+  const origin = normalizeWebOrigin(webOrigin);
+  let record;
+  try {
+    record = JSON.parse(
+      await readFile(connectionDiscoveryPath(origin, sessionRoot), "utf8"),
+    );
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw connectionError("connection_service_mismatch");
+  }
+  if (
+    record?.schema_version !== 1 ||
+    record.web_origin !== origin ||
+    !Number.isInteger(record.port) ||
+    record.port < 1 ||
+    record.port > 65535 ||
+    !Number.isInteger(record.pid) ||
+    record.pid <= 0 ||
+    typeof record.instance_id !== "string" ||
+    !record.instance_id
+  ) {
+    throw connectionError("connection_service_mismatch");
+  }
+  if (!alive(record.pid)) return null;
+  let response, health;
+  try {
+    response = await fetchImpl(
+      `http://127.0.0.1:${record.port}/v1/connection`,
+      {
+        signal: AbortSignal.timeout(1500),
+        redirect: "error",
+        cache: "no-store",
+      },
+    );
+    health = response.ok ? await response.json() : null;
+  } catch {
+    throw connectionError("connection_service_unavailable");
+  }
+  if (response.status === 404)
+    throw connectionError("connection_service_incompatible");
+  if (
+    !health?.ok ||
+    health.instance_id !== record.instance_id ||
+    health.pid !== record.pid ||
+    health.web_origin !== origin
+  ) {
+    throw connectionError("connection_service_mismatch");
+  }
+  if (health.daemon !== true)
+    throw connectionError("connection_service_not_background");
+  if (requestedPort && requestedPort !== record.port)
+    throw connectionError("connection_port_mismatch");
+  if (
+    !compatibleServiceVersion(health.cli_version, cliVersion) ||
+    health.api_contract_version !== apiContractVersion
+  )
+    throw connectionError("connection_service_incompatible");
+  assertConnectionScope(expectedScope, health.scope);
+  if (authorize && (reauthorize || !health.session_valid)) {
+    try {
+      response = await fetchImpl(
+        `http://127.0.0.1:${record.port}/v1/connection`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            instance_id: record.instance_id,
+            scope: health.scope,
+            reauthorize,
+          }),
+          signal: AbortSignal.timeout(1500),
+          redirect: "error",
+          cache: "no-store",
+        },
+      );
+      health = await response.json().catch(() => null);
+    } catch {
+      throw connectionError("connection_service_unavailable");
+    }
+    if (!response.ok && health?.code === "connection_scope_changed" &&
+        ["web_origin", "account_id", "organization_id", "device_id"].includes(health.field)) {
+      const diagnostic = connectionDiagnostic(health.code, health.field);
+      throw Object.assign(new Error(diagnostic.error), diagnostic);
+    }
+    if (!response.ok) throw connectionError("connection_service_mismatch");
+    if (
+      !health?.ok ||
+      health.instance_id !== record.instance_id ||
+      health.pid !== record.pid ||
+      health.web_origin !== origin
+    ) {
+      throw connectionError("connection_service_mismatch");
+    }
+    assertConnectionScope(expectedScope, health.scope);
+  }
+  if (health.login_url !== null) {
+    let url;
+    try {
+      url = new URL(health.login_url);
+    } catch {
+      throw connectionError("connection_service_mismatch");
+    }
+    if (
+      url.origin !== origin ||
+      url.pathname !== "/local-cli/connect" ||
+      url.searchParams.get("port") !== String(record.port)
+    ) {
+      throw connectionError("connection_service_mismatch");
+    }
+  }
+  return {
+    port: record.port,
+    webOrigin: origin,
+    loginUrl: health.login_url,
+    sessionValid: health.session_valid === true,
+  };
+}
+
+function connectionError(code) {
+  const diagnostic = connectionDiagnostic(code);
+  return Object.assign(new Error(diagnostic.error), diagnostic);
+}
+
+function compatibleServiceVersion(running, requested) {
+  const version = (value) =>
+    typeof value === "string"
+      ? /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(value)
+      : null;
+  const existing = version(running),
+    target = version(requested);
+  return Boolean(
+    existing &&
+    target &&
+    existing[1] === target[1] &&
+    (existing[1] !== "0" || existing[2] === target[2]),
+  );
+}

package/src/index.js

@@ -6,6 +6,10 @@ import { createInterface } from "node:readline/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { findReusableConnection } from "./connection-discovery.js";
+import { connectionScope } from "./connection-diagnostics.js";
+import { readSession } from "./session-store.js";
+import { CLI_API_CONTRACT_VERSION } from "./cli-contract.js";
 import { startAgent } from "./agent.js";
 import { createRuntimeDiagnostics, captureRuntimeOutput } from "./runtime-diagnostics.js";
 import {
@@ -165,6 +169,23 @@ async function runLocalAgent() {
   const webOrigin = configuredWebOrigin;
   const sessionRoot = process.env.SIMY_HOME?.trim() || join(homedir(), ".simy");
 
+  try {
+    const existing = await findReusableConnection({ webOrigin, sessionRoot, cliVersion: packageInfo.version,
+      apiContractVersion: CLI_API_CONTRACT_VERSION, requestedPort: port, authorize: true,
+      expectedScope: connectionScope(await readSession(webOrigin, sessionRoot), webOrigin) });
+    if (existing) {
+      console.log(`Connected to existing SIMY service at http://127.0.0.1:${existing.port}`);
+      const url = existing.loginUrl || webOrigin;
+      console.log(`Continue in SIMY Web: ${url}`);
+      if (!args.has('--no-open') && process.env.SIMY_DAEMON_CHILD !== '1') await openAuthorizationUrl(url);
+      return;
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 2;
+    return;
+  }
+
   try {
     await prepareDaemonWorkflows({ argv, daemon });
   } catch (error) {

package/src/launch-authorization.js

@@ -0,0 +1,80 @@
+import { webApiHeaders, webApiUrl } from "./web-api.js";
+
+// Only an explicitly expired credential is renewable. A consumed or rejected
+// credential may represent an execution that already started; never replay it.
+export async function authorizeLaunch({
+  apiOrigin,
+  apiBaseUrl,
+  token,
+  runId,
+  challenge,
+  fetchImpl = fetch,
+}) {
+  const post = async (path, body) => {
+    const response = await fetchImpl(
+      webApiUrl(path, { webOrigin: apiOrigin, apiBaseUrl }),
+      {
+        method: "POST",
+        headers: webApiHeaders(
+          { token },
+          { "Content-Type": "application/json" },
+        ),
+        body: JSON.stringify(body),
+        redirect: "error",
+        signal: AbortSignal.timeout(10_000),
+      },
+    );
+    return { response, payload: await response.json().catch(() => null) };
+  };
+  const rejected = ({ response, payload }) => ({
+    ok: false,
+    status: response.status >= 500 ? 502 : response.status === 401 ? 401 : 403,
+    code:
+      typeof payload?.code === "string"
+        ? payload.code
+        : response.status >= 500
+          ? "launch_service_unavailable"
+          : response.status === 401
+            ? "connection_session_expired"
+            : response.status === 404
+              ? "launch_service_incompatible"
+              : "launch_challenge_invalid",
+  });
+  const verificationOutcome = (result) => {
+    if (!result.response.ok) return rejected(result);
+    return result.payload?.ok === true
+      ? { ok: true }
+      : { ok: false, status: 502, code: "launch_service_unavailable" };
+  };
+  try {
+    if (challenge) {
+      const verified = await post("challenges/verify", {
+        run_id: runId,
+        challenge,
+      });
+      if (verified.response.ok) return verificationOutcome(verified);
+      if (verified.payload?.code !== "launch_challenge_expired")
+        return rejected(verified);
+    }
+    const issued = await post("challenges/issue", {
+      run_id: runId,
+      ...(challenge ? { previous_challenge: challenge } : {}),
+    });
+    if (!issued.response.ok) return rejected(issued);
+    if (
+      typeof issued.payload?.challenge !== "string" ||
+      !issued.payload.challenge ||
+      !Number.isFinite(Date.parse(issued.payload.expires_at)) ||
+      Date.parse(issued.payload.expires_at) <= Date.now()
+    ) {
+      return { ok: false, status: 502, code: "launch_service_unavailable" };
+    }
+    const verified = await post("challenges/verify", {
+      run_id: runId,
+      challenge: issued.payload.challenge,
+    });
+    return verificationOutcome(verified);
+  } catch {
+    return { ok: false, status: 502, code: "launch_service_unavailable" };
+  }
+}

package/src/sqm/session.js

@@ -1,3 +1,6 @@
+import { findReusableConnection } from "../connection-discovery.js";
+import { connectionScope } from "../connection-diagnostics.js";
+import { CLI_VERSION, CLI_API_CONTRACT_VERSION } from "../cli-contract.js";
 import { startAgent } from "../agent.js";
 import { openAuthorizationUrl } from "../browser.js";
 import { isSessionValid, readSession } from "../session-store.js";
@@ -16,6 +19,7 @@ export async function ensureSqmSession(
     readSessionImpl = readSession,
     isSessionValidImpl = isSessionValid,
     startAgentImpl = startAgent,
+    findConnectionImpl = findReusableConnection,
     openAuthorizationUrlImpl = openAuthorizationUrl,
     createAgentShutdownImpl = createAgentShutdown,
     expectedScope,
@@ -31,8 +35,11 @@ export async function ensureSqmSession(
     return session;
   }
 
-  const agent = await startAgentImpl({ requestedPort: 0, webOrigin, quiet: true });
-  const shutdown = createAgentShutdownImpl(agent);
+  const existing = await findConnectionImpl({ webOrigin, cliVersion: CLI_VERSION,
+    apiContractVersion: CLI_API_CONTRACT_VERSION, expectedScope: connectionScope(session, webOrigin),
+    authorize: true, reauthorize: session?.token === rejectedToken && Boolean(rejectedToken) });
+  const agent = existing || await startAgentImpl({ requestedPort: 0, webOrigin, quiet: true });
+  const shutdown = existing ? async () => {} : createAgentShutdownImpl(agent);
   try {
     const loginUrl = agent.loginUrl;
     if (!loginUrl) throw new Error("SIMY could not create an SQM authorization session.");