viveworker 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuta Hoshino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,5 +1,10 @@
+![viveworker social preview](./assets/app-screenshot.png)
+
 # viveworker
 
+[![npm version](https://badge.fury.io/js/viveworker.svg)](https://badge.fury.io/js/viveworker)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 `viveworker` brings Codex Desktop to your iPhone.
 
 When Codex needs an approval, asks whether to implement a plan, wants you to choose from options, or finishes a task while you are away from your desk, `viveworker` keeps all of that within reach on your phone. Instead of breaking your rhythm, it helps you keep vivecoding going from anywhere in your home or office.

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "viveworker",
-  "version": "0.1.1",
-  "description": "A local iPhone companion for Codex Desktop approvals, plans, questions, and completions.",
-  "author": "oeneril <hoshino.lireneo@gmail.com>",
+  "version": "0.1.3",
+  "description": "Local iPhone companion for Codex Desktop approvals, plan checks, questions, and notifications on your LAN.",
+  "author": "Yuta Hoshino <hoshino.lireneo@gmail.com>",
+  "license": "MIT",
   "keywords": [
-    "vivecoding",
     "codex",
-    "remote"
+    "codex-desktop",
+    "macos",
+    "iphone",
+    "ios",
+    "pwa",
+    "web-push",
+    "notifications",
+    "approvals",
+    "lan",
+    "companion-app",
+    "vivecoding"
   ],
   "homepage": "https://lp.hazbase.com/",
-  "repository": "viveworker/viveworker",
+  "repository": "viveworker-dev/viveworker",
   "type": "module",
   "bin": {
     "viveworker": "./scripts/viveworker.mjs"

package/scripts/viveworker-bridge.mjs

@@ -31,6 +31,9 @@ const DEFAULT_DEVICE_TRUST_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const MAX_PAIRED_DEVICES = 200;
 const PAIRING_RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000;
 const PAIRING_RATE_LIMIT_MAX_ATTEMPTS = 8;
+const DEFAULT_COMPLETION_REPLY_IMAGE_MAX_BYTES = 15 * 1024 * 1024;
+const DEFAULT_COMPLETION_REPLY_UPLOAD_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_COMPLETION_REPLY_IMAGE_COUNT = 1;
 
 const cli = parseCliArgs(process.argv.slice(2));
 const envFile = resolveEnvFile(cli.envFile);
@@ -4406,6 +4409,7 @@ function readSession(req, config, state) {
     pairedAtMs: Number(payload.pairedAtMs) || 0,
     expiresAtMs: Number(payload.expiresAtMs) || 0,
     deviceId,
+    temporaryPairing: payload?.temporaryPairing === true,
   };
 }
 
@@ -4463,6 +4467,22 @@ function setSessionCookie(res, config) {
   }));
 }
 
+function setTemporarySessionCookie(res, config) {
+  const secure = config.nativeApprovalPublicBaseUrl.startsWith("https://");
+  const now = Date.now();
+  const token = signSessionPayload({
+    sessionId: crypto.randomUUID(),
+    pairedAtMs: now,
+    expiresAtMs: now + config.sessionTtlMs,
+    temporaryPairing: true,
+  }, config.sessionSecret);
+  res.setHeader("Set-Cookie", buildSetCookieHeader({
+    value: token,
+    maxAgeSecs: Math.max(1, Math.floor(config.sessionTtlMs / 1000)),
+    secure,
+  }));
+}
+
 function clearSessionCookie(res, config) {
   const secure = config.nativeApprovalPublicBaseUrl.startsWith("https://");
   res.setHeader("Set-Cookie", buildSetCookieHeader({ value: "", maxAgeSecs: 0, secure }));
@@ -4620,15 +4640,27 @@ function pairingCredentialConsumed(config, state) {
 }
 
 function isPairingAvailableForState(config, state) {
-  return isPairingAvailable(config) && !pairingCredentialConsumed(config, state);
+  return isPairingAvailable(config) && !pairingCodeConsumed(config, state);
 }
 
-function markPairingConsumed(state, config, now = Date.now()) {
-  const current = currentPairingCredential(config);
+function pairingCodeConsumed(config, state) {
+  const code = cleanText(config?.pairingCode ?? "").toUpperCase();
+  if (!code) {
+    return false;
+  }
+  const consumedAtMs = Number(state?.pairingConsumedAt) || 0;
+  const consumedCredential = cleanText(state?.pairingConsumedCredential ?? "");
+  return consumedAtMs > 0 && consumedCredential === `code:${code}`;
+}
+
+function markPairingConsumed(state, credential, now = Date.now()) {
+  const current = cleanText(credential || "");
   if (!current) {
     return false;
   }
-  if (pairingCredentialConsumed(config, state)) {
+  const consumedAtMs = Number(state?.pairingConsumedAt) || 0;
+  const consumedCredential = cleanText(state?.pairingConsumedCredential ?? "");
+  if (consumedAtMs > 0 && consumedCredential === current) {
     return false;
   }
   state.pairingConsumedAt = now;
@@ -4640,7 +4672,7 @@ function validatePairingPayload(payload, config, state) {
   if (!config.authRequired) {
     return { ok: true };
   }
-  if (!isPairingAvailableForState(config, state)) {
+  if (!isPairingAvailable(config)) {
     return { ok: false, error: "pairing-unavailable" };
   }
 
@@ -4648,10 +4680,16 @@ function validatePairingPayload(payload, config, state) {
   const token = cleanText(payload?.token ?? "");
   const matchesCode = code && cleanText(config.pairingCode).toUpperCase() === code;
   const matchesToken = token && cleanText(config.pairingToken) === token;
-  if (!matchesCode && !matchesToken) {
-    return { ok: false, error: "invalid-pairing-credentials" };
+  if (matchesToken) {
+    return { ok: true, credential: `token:${token}` };
   }
-  return { ok: true };
+  if (matchesCode) {
+    if (pairingCodeConsumed(config, state)) {
+      return { ok: false, error: "pairing-unavailable" };
+    }
+    return { ok: true, credential: `code:${code}` };
+  }
+  return { ok: false, error: "invalid-pairing-credentials" };
 }
 
 function readRemoteAddress(req) {
@@ -5437,8 +5475,25 @@ async function submitGenericUserInputDecision({ config, runtime, state, userInpu
   }
 }
 
-async function handleCompletionReply({ runtime, completionItem, text, planMode = false, force = false }) {
+function normalizeCompletionReplyLocalImagePaths(paths) {
+  if (!Array.isArray(paths)) {
+    return [];
+  }
+  return paths
+    .map((value) => resolvePath(cleanText(value || "")))
+    .filter(Boolean);
+}
+
+async function handleCompletionReply({
+  runtime,
+  completionItem,
+  text,
+  planMode = false,
+  force = false,
+  localImagePaths = [],
+}) {
   const messageText = cleanText(text ?? "");
+  const normalizedLocalImagePaths = normalizeCompletionReplyLocalImagePaths(localImagePaths);
   if (!messageText) {
     throw new Error("completion-reply-empty");
   }
@@ -5472,6 +5527,10 @@ async function handleCompletionReply({ runtime, completionItem, text, planMode =
   const turnStartParams = {
     input: buildTextInput(messageText),
     attachments: [],
+    localImagePaths: normalizedLocalImagePaths,
+    local_image_paths: normalizedLocalImagePaths,
+    remoteImageUrls: [],
+    remote_image_urls: [],
     cwd: null,
     approvalPolicy: null,
     sandboxPolicy: null,
@@ -5683,7 +5742,7 @@ function resolveManifestPairingToken({ config, state, requestedToken }) {
   if (!token) {
     return "";
   }
-  if (!isPairingAvailableForState(config, state)) {
+  if (!isPairingAvailable(config)) {
     return "";
   }
   return cleanText(config.pairingToken) === token ? token : "";
@@ -5836,6 +5895,7 @@ function createNativeApprovalServer({ config, runtime, state }) {
           httpsEnabled: config.nativeApprovalPublicBaseUrl.startsWith("https://"),
           appVersion: appPackageVersion,
           deviceId: session.deviceId || null,
+          temporaryPairing: session.temporaryPairing === true,
           ...buildSessionLocalePayload(config, state, session.deviceId),
         });
       }
@@ -5860,6 +5920,17 @@ function createNativeApprovalServer({ config, runtime, state }) {
           return writeJson(res, 400, { error: validation.error });
         }
 
+        if (payload?.temporary === true && cleanText(payload?.token || "")) {
+          clearPairingFailures(runtime, remoteAddress);
+          setTemporarySessionCookie(res, config);
+          return writeJson(res, 200, {
+            ok: true,
+            authenticated: true,
+            pairingAvailable: isPairingAvailableForState(config, state),
+            temporaryPairing: true,
+          });
+        }
+
         const pairedDeviceId = readDeviceId(req, config) || crypto.randomUUID();
         if ("detectedLocale" in payload) {
           upsertDetectedDeviceLocale(state, pairedDeviceId, payload.detectedLocale);
@@ -5874,7 +5945,9 @@ function createNativeApprovalServer({ config, runtime, state }) {
             lastLocale: normalizeSupportedLocale(payload?.detectedLocale),
           }
         );
-        markPairingConsumed(state, config);
+        if (String(validation.credential || "").startsWith("code:")) {
+          markPairingConsumed(state, validation.credential);
+        }
         clearPairingFailures(runtime, remoteAddress);
         await saveState(config.stateFile, state);
         setPairingCookies(res, config, pairedDeviceId);
@@ -6112,22 +6185,36 @@ function createNativeApprovalServer({ config, runtime, state }) {
         }
 
         try {
-          const payload = await parseJsonBody(req);
+          const contentType = String(req.headers["content-type"] || "");
+          const payload = contentType.includes("multipart/form-data")
+            ? await stageCompletionReplyImages(config, req)
+            : await parseJsonBody(req);
           await handleCompletionReply({
             runtime,
             completionItem,
             text: payload?.text ?? "",
             planMode: payload?.planMode === true,
             force: payload?.force === true,
+            localImagePaths: Array.isArray(payload?.localImagePaths) ? payload.localImagePaths : [],
           });
           return writeJson(res, 200, {
             ok: true,
             planMode: payload?.planMode === true,
+            imageCount: Array.isArray(payload?.localImagePaths) ? payload.localImagePaths.length : 0,
           });
         } catch (error) {
           if (error.message === "completion-reply-empty") {
             return writeJson(res, 400, { error: error.message });
           }
+          if (
+            error.message === "completion-reply-image-limit" ||
+            error.message === "completion-reply-image-invalid-type" ||
+            error.message === "completion-reply-image-too-large" ||
+            error.message === "completion-reply-image-invalid-upload" ||
+            error.message === "completion-reply-image-disabled"
+          ) {
+            return writeJson(res, 400, { error: error.message });
+          }
           if (error.message === "completion-reply-unavailable") {
             return writeJson(res, 409, { error: error.message });
           }
@@ -6766,6 +6853,20 @@ async function parseFormBody(req) {
   });
 }
 
+async function parseMultipartBody(req) {
+  const contentLength = Number(req.headers["content-length"]) || 0;
+  if (contentLength > 32 * 1024 * 1024) {
+    throw new Error("request-body-too-large");
+  }
+  const request = new Request("http://localhost/upload", {
+    method: req.method || "POST",
+    headers: req.headers,
+    body: req,
+    duplex: "half",
+  });
+  return request.formData();
+}
+
 async function parseJsonBody(req) {
   return new Promise((resolve, reject) => {
     let body = "";
@@ -6788,6 +6889,94 @@ async function parseJsonBody(req) {
   });
 }
 
+function guessUploadExtension(fileName, mimeType) {
+  const explicitExtension = path.extname(cleanText(fileName || ""));
+  if (explicitExtension) {
+    return explicitExtension.toLowerCase();
+  }
+  const normalizedMimeType = cleanText(mimeType || "").toLowerCase();
+  const knownExtensions = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "image/heic": ".heic",
+    "image/heif": ".heif",
+  };
+  return knownExtensions[normalizedMimeType] || ".img";
+}
+
+async function cleanupExpiredCompletionReplyUploads(config) {
+  try {
+    const entries = await fs.readdir(config.replyUploadsDir, { withFileTypes: true });
+    const cutoffMs = Date.now() - config.completionReplyUploadTtlMs;
+    await Promise.all(entries.map(async (entry) => {
+      if (!entry.isFile()) {
+        return;
+      }
+      const filePath = path.join(config.replyUploadsDir, entry.name);
+      try {
+        const stat = await fs.stat(filePath);
+        if (Number(stat.mtimeMs) < cutoffMs) {
+          await fs.rm(filePath, { force: true });
+        }
+      } catch {
+        // Ignore best-effort cleanup errors.
+      }
+    }));
+  } catch {
+    // Ignore missing upload dir.
+  }
+}
+
+async function stageCompletionReplyImages(config, req) {
+  const formData = await parseMultipartBody(req);
+  const files = formData
+    .getAll("image")
+    .filter((value) => typeof File !== "undefined" && value instanceof File);
+
+  if (files.length > 0) {
+    throw new Error("completion-reply-image-disabled");
+  }
+
+  if (files.length > MAX_COMPLETION_REPLY_IMAGE_COUNT) {
+    throw new Error("completion-reply-image-limit");
+  }
+
+  await cleanupExpiredCompletionReplyUploads(config);
+  await fs.mkdir(config.replyUploadsDir, { recursive: true });
+
+  const localImagePaths = [];
+  for (const file of files) {
+    const mimeType = cleanText(file.type || "").toLowerCase();
+    if (!mimeType.startsWith("image/")) {
+      throw new Error("completion-reply-image-invalid-type");
+    }
+    if (!Number.isFinite(file.size) || file.size <= 0) {
+      throw new Error("completion-reply-image-invalid-upload");
+    }
+    if (file.size > config.completionReplyImageMaxBytes) {
+      throw new Error("completion-reply-image-too-large");
+    }
+
+    const extension = guessUploadExtension(file.name, mimeType);
+    const stagedFilePath = path.join(
+      config.replyUploadsDir,
+      `${Date.now()}-${crypto.randomUUID()}${extension}`
+    );
+    const buffer = Buffer.from(await file.arrayBuffer());
+    await fs.writeFile(stagedFilePath, buffer, { mode: 0o600 });
+    localImagePaths.push(stagedFilePath);
+  }
+
+  return {
+    text: cleanText(formData.get("text") ?? ""),
+    planMode: String(formData.get("planMode") ?? "") === "true",
+    force: String(formData.get("force") ?? "") === "true",
+    localImagePaths,
+  };
+}
+
 function isLoopbackRequest(req) {
   const remoteAddress = cleanText(req.socket?.remoteAddress ?? "");
   return (
@@ -7727,6 +7916,7 @@ function isLoopbackHostname(value) {
 
 function buildConfig(cli) {
   const codexHome = resolvePath(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"));
+  const stateFile = resolvePath(process.env.STATE_FILE || path.join(workspaceRoot, ".viveworker-state.json"));
   return {
     dryRun: cli.dryRun || truthy(process.env.DRY_RUN),
     once: cli.once,
@@ -7740,7 +7930,8 @@ function buildConfig(cli) {
     sessionIndexFile: resolvePath(process.env.SESSION_INDEX_FILE || path.join(codexHome, "session_index.jsonl")),
     historyFile: resolvePath(process.env.HISTORY_FILE || path.join(codexHome, "history.jsonl")),
     codexLogsDbFile: resolvePath(process.env.CODEX_LOGS_DB_FILE || ""),
-    stateFile: resolvePath(process.env.STATE_FILE || path.join(workspaceRoot, ".viveworker-state.json")),
+    stateFile,
+    replyUploadsDir: resolvePath(process.env.REPLY_UPLOADS_DIR || path.join(path.dirname(stateFile), "uploads")),
     pollIntervalMs: numberEnv("POLL_INTERVAL_MS", 2500),
     replaySeconds: numberEnv("REPLAY_SECONDS", 300),
     sessionIndexRefreshMs: numberEnv("SESSION_INDEX_REFRESH_MS", 30000),
@@ -7794,6 +7985,14 @@ function buildConfig(cli) {
     ipcReconnectMs: numberEnv("IPC_RECONNECT_MS", 1500),
     ipcRequestTimeoutMs: numberEnv("IPC_REQUEST_TIMEOUT_MS", 12000),
     choicePageSize: numberEnv("CHOICE_PAGE_SIZE", 5),
+    completionReplyImageMaxBytes: numberEnv(
+      "COMPLETION_REPLY_IMAGE_MAX_BYTES",
+      DEFAULT_COMPLETION_REPLY_IMAGE_MAX_BYTES
+    ),
+    completionReplyUploadTtlMs: numberEnv(
+      "COMPLETION_REPLY_UPLOAD_TTL_MS",
+      DEFAULT_COMPLETION_REPLY_UPLOAD_TTL_MS
+    ),
     deviceTrustTtlMs: numberEnv("DEVICE_TRUST_TTL_MS", DEFAULT_DEVICE_TRUST_TTL_MS),
     sessionTtlMs: numberEnv("SESSION_TTL_MS", 30 * 24 * 60 * 60 * 1000),
     pairingCode: process.env.PAIRING_CODE || "",
@@ -7907,9 +8106,7 @@ function loadEnvFile(filePath) {
       if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
         value = value.slice(1, -1);
       }
-      if (!process.env[key]) {
-        process.env[key] = value;
-      }
+      process.env[key] = value;
     }
   } catch {
     // Optional env file.

package/scripts/viveworker.mjs

@@ -200,7 +200,14 @@ async function runSetup(cliOptions) {
 
   progress.update("cli.setup.progress.health");
   const healthy = await waitForHealth(buildLoopbackHealthUrl(publicBaseUrl));
-  progress.done(healthy ? "cli.setup.complete" : "cli.setup.completePending");
+  const pairingReady = healthy
+    ? await waitForExpectedPairing(publicBaseUrl, pairToken)
+    : false;
+  progress.done(healthy && pairingReady ? "cli.setup.complete" : "cli.setup.completePending");
+  if (healthy && !pairingReady) {
+    console.log("");
+    console.log(t(locale, "cli.setup.warning.stalePairingServer", { port }));
+  }
 
   const pairPath = `/app?pairToken=${encodeURIComponent(pairToken)}`;
   const mkcertRootCaFile = resolvePath(
@@ -258,7 +265,7 @@ async function runSetup(cliOptions) {
   if (allowInsecureHttpLan) {
     console.log(t(locale, "cli.setup.warning.insecureHttpLan"));
   }
-  if (canShowCaDownload && !cliOptions.installMkcert) {
+  if (canShowCaDownload && !cliOptions.installMkcert && !cliOptions.pair) {
     console.log(t(locale, "cli.setup.caDownloadLocal", { url: caDownloadLocalUrl }));
     console.log(t(locale, "cli.setup.caDownloadIp", { url: caDownloadIpUrl }));
   }
@@ -273,7 +280,7 @@ async function runSetup(cliOptions) {
   console.log("");
   console.log(t(locale, "cli.setup.qrPairing"));
   await printQrCode(`${publicBaseUrl}${pairPath}`);
-  if (canShowCaDownload && !cliOptions.installMkcert) {
+  if (canShowCaDownload && !cliOptions.installMkcert && !cliOptions.pair) {
     console.log("");
     console.log(t(locale, "cli.setup.qrCaDownload"));
     await printQrCode(caDownloadIpUrl);
@@ -309,7 +316,14 @@ async function runStart(cliOptions) {
     await execCommand(["launchctl", "kickstart", "-k", `gui/${process.getuid()}/${defaultLabel}`]);
     progress.update("cli.start.progress.health");
     const healthy = await waitForHealth(healthUrl);
-    progress.done(healthy ? "cli.start.launchdStarted" : "cli.start.launchdStartedPending");
+    const pairingReady = healthy && rotatedPairing.rotated
+      ? await waitForExpectedPairing(config.NATIVE_APPROVAL_SERVER_PUBLIC_BASE_URL || "", rotatedPairing.pairingToken)
+      : true;
+    progress.done(healthy && pairingReady ? "cli.start.launchdStarted" : "cli.start.launchdStartedPending");
+    if (healthy && !pairingReady) {
+      console.log("");
+      console.log(t(locale, "cli.setup.warning.stalePairingServer", { port: config.NATIVE_APPROVAL_SERVER_PORT || defaultServerPort }));
+    }
     if (rotatedPairing.rotated) {
       await printPairingInfo(locale, config);
     }
@@ -324,7 +338,14 @@ async function runStart(cliOptions) {
   });
   progress.update("cli.start.progress.health");
   const healthy = await waitForHealth(healthUrl);
-  progress.done(healthy ? "cli.start.bridgeStarted" : "cli.start.bridgeStartedPending");
+  const pairingReady = healthy && rotatedPairing.rotated
+    ? await waitForExpectedPairing(config.NATIVE_APPROVAL_SERVER_PUBLIC_BASE_URL || "", rotatedPairing.pairingToken)
+    : true;
+  progress.done(healthy && pairingReady ? "cli.start.bridgeStarted" : "cli.start.bridgeStartedPending");
+  if (healthy && !pairingReady) {
+    console.log("");
+    console.log(t(locale, "cli.setup.warning.stalePairingServer", { port: config.NATIVE_APPROVAL_SERVER_PORT || defaultServerPort }));
+  }
   if (rotatedPairing.rotated) {
     await printPairingInfo(locale, config);
   }
@@ -982,6 +1003,33 @@ function buildLoopbackHealthUrl(baseUrl) {
   }
 }
 
+function buildLoopbackUrl(baseUrl, pathname, searchParams = null) {
+  if (!baseUrl) {
+    return "";
+  }
+  try {
+    const url = new URL(baseUrl);
+    url.hostname = "127.0.0.1";
+    url.pathname = pathname;
+    url.search = "";
+    url.hash = "";
+    if (searchParams && Object.keys(searchParams).length > 0) {
+      const params = new URLSearchParams();
+      for (const [key, value] of Object.entries(searchParams)) {
+        if (value == null || value === "") {
+          continue;
+        }
+        params.set(key, String(value));
+      }
+      const serialized = params.toString();
+      url.search = serialized ? `?${serialized}` : "";
+    }
+    return url.toString();
+  } catch {
+    return "";
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1105,6 +1153,34 @@ async function waitForHealth(url, { attempts = 8, intervalMs = 500 } = {}) {
   return false;
 }
 
+async function waitForExpectedPairing(baseUrl, pairToken, { attempts = 8, intervalMs = 500 } = {}) {
+  const token = String(pairToken || "").trim();
+  const manifestUrl = buildLoopbackUrl(baseUrl, "/manifest.webmanifest", { pairToken: token });
+  const expectedStartUrl = `/app?pairToken=${encodeURIComponent(token)}`;
+  if (!token || !manifestUrl) {
+    return false;
+  }
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const result = await execCommand(buildHealthCheckArgs(manifestUrl), { ignoreError: true });
+    if (result.ok) {
+      try {
+        const payload = JSON.parse(result.stdout);
+        if (String(payload?.start_url || "").trim() === expectedStartUrl) {
+          return true;
+        }
+      } catch {
+        // Keep retrying while the new bridge instance comes up.
+      }
+    }
+    if (attempt < attempts - 1) {
+      await sleep(intervalMs);
+    }
+  }
+
+  return false;
+}
+
 function truthyString(value) {
   return /^(1|true|yes|on)$/iu.test(String(value || "").trim());
 }

package/web/app.css

@@ -1541,6 +1541,90 @@ code {
   color: rgba(205, 220, 231, 0.42);
 }
 
+.reply-attachment-field {
+  display: grid;
+  gap: 0.55rem;
+}
+
+.reply-attachment-field__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+}
+
+.reply-attachment-picker {
+  display: grid;
+  gap: 0.18rem;
+  padding: 0.88rem 0.95rem;
+  border-radius: 18px;
+  border: 1px dashed rgba(156, 181, 197, 0.24);
+  background: rgba(255, 255, 255, 0.03);
+  cursor: pointer;
+}
+
+.reply-attachment-picker__input {
+  position: absolute;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.reply-attachment-picker__label {
+  font-size: 0.93rem;
+  font-weight: 700;
+  color: #eef8ff;
+}
+
+.reply-attachment-picker__hint {
+  font-size: 0.82rem;
+  color: var(--muted);
+  line-height: 1.42;
+}
+
+.reply-image-preview {
+  display: grid;
+  grid-template-columns: 4.5rem minmax(0, 1fr);
+  gap: 0.8rem;
+  align-items: center;
+  padding: 0.78rem 0.85rem;
+  border-radius: 18px;
+  border: 1px solid rgba(156, 181, 197, 0.12);
+  background: rgba(255, 255, 255, 0.04);
+}
+
+.reply-image-preview__image {
+  width: 4.5rem;
+  height: 4.5rem;
+  object-fit: cover;
+  border-radius: 14px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  background: rgba(6, 10, 14, 0.92);
+}
+
+.reply-image-preview__copy {
+  min-width: 0;
+  display: grid;
+  gap: 0.14rem;
+}
+
+.reply-image-preview__name,
+.reply-image-preview__meta {
+  margin: 0;
+}
+
+.reply-image-preview__name {
+  color: #eef8ff;
+  font-size: 0.91rem;
+  font-weight: 600;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+
+.reply-image-preview__meta {
+  color: var(--muted);
+  font-size: 0.8rem;
+}
+
 .reply-mode-switch {
   display: grid;
   grid-template-columns: auto auto minmax(0, 1fr);

package/web/app.js

@@ -87,9 +87,12 @@ async function boot() {
 
   await refreshSession();
 
-  if (!state.session?.authenticated && initialPairToken) {
+  if (!state.session?.authenticated && initialPairToken && shouldAutoPairFromBootstrapToken()) {
     try {
-      await pair({ token: initialPairToken });
+      await pair({
+        token: initialPairToken,
+        temporary: shouldUseTemporaryBootstrapPairing(),
+      });
     } catch (error) {
       state.pairError = error.message || String(error);
     }
@@ -480,6 +483,7 @@ function syncCompletedThreadFilter() {
 }
 
 function renderPair() {
+  const shouldInstallFromHomeScreen = Boolean(initialPairToken) && !shouldAutoPairFromBootstrapToken();
   app.innerHTML = `
     <main class="onboarding-shell">
       <section class="onboarding-card">
@@ -488,6 +492,7 @@ function renderPair() {
         <p class="hero-copy">${escapeHtml(L("pair.copy"))}</p>
         ${state.pairNotice ? `<p class="inline-alert inline-alert--success">${escapeHtml(state.pairNotice)}</p>` : ""}
         ${state.pairError ? `<p class="inline-alert inline-alert--danger">${escapeHtml(state.pairError)}</p>` : ""}
+        ${shouldInstallFromHomeScreen ? `<p class="inline-alert inline-alert--warning">${escapeHtml(L("pair.installFromHomeScreen"))}</p>` : ""}
         <form id="pair-form" class="pair-form">
           <label class="field">
             <span class="field-label">${escapeHtml(L("pair.codeLabel"))}</span>
@@ -530,7 +535,9 @@ function renderPair() {
 
 async function pair(payload) {
   const result = await apiPost("/api/session/pair", payload);
-  syncPairingTokenState("");
+  if (result?.temporaryPairing !== true) {
+    syncPairingTokenState("");
+  }
   return result;
 }
 
@@ -555,6 +562,7 @@ function resetAuthenticatedState() {
   state.detailLoadingItem = null;
   state.detailOpen = false;
   state.choiceLocalDrafts = {};
+  clearAllCompletionReplyDrafts();
   state.completionReplyDrafts = {};
   state.settingsSubpage = "";
   state.settingsScrollState = null;
@@ -765,11 +773,70 @@ function normalizeReplyMode(value) {
   return normalizeClientText(value).toLowerCase() === "plan" ? "plan" : "default";
 }
 
+const COMPLETION_REPLY_IMAGE_SUPPORT = false;
+
+function normalizeCompletionReplyAttachment(value) {
+  if (!COMPLETION_REPLY_IMAGE_SUPPORT) {
+    return null;
+  }
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const file = typeof File !== "undefined" && value.file instanceof File ? value.file : null;
+  const name = normalizeClientText(value.name || file?.name || "");
+  const type = normalizeClientText(value.type || file?.type || "");
+  const size = Number(value.size ?? file?.size) || 0;
+  const previewUrl = normalizeClientText(value.previewUrl || "");
+  if (!file || !name || !type.startsWith("image/") || size <= 0) {
+    return null;
+  }
+  return {
+    file,
+    name,
+    type,
+    size,
+    previewUrl,
+  };
+}
+
+function createCompletionReplyAttachment(file) {
+  if (!COMPLETION_REPLY_IMAGE_SUPPORT) {
+    return null;
+  }
+  if (!(typeof File !== "undefined" && file instanceof File)) {
+    return null;
+  }
+  if (!normalizeClientText(file.type).startsWith("image/")) {
+    return null;
+  }
+  return normalizeCompletionReplyAttachment({
+    file,
+    name: file.name,
+    type: file.type,
+    size: file.size,
+    previewUrl: typeof URL !== "undefined" && typeof URL.createObjectURL === "function"
+      ? URL.createObjectURL(file)
+      : "",
+  });
+}
+
+function releaseCompletionReplyAttachment(attachment) {
+  if (!attachment?.previewUrl || typeof URL === "undefined" || typeof URL.revokeObjectURL !== "function") {
+    return;
+  }
+  try {
+    URL.revokeObjectURL(attachment.previewUrl);
+  } catch {
+    // Ignore best-effort object URL cleanup errors.
+  }
+}
+
 function getCompletionReplyDraft(token) {
   if (!token) {
     return {
       text: "",
       sentText: "",
+      attachment: null,
       mode: "default",
       notice: "",
       error: "",
@@ -784,6 +851,7 @@ function getCompletionReplyDraft(token) {
   return {
     text: String(draft.text ?? ""),
     sentText: normalizeClientText(draft.sentText ?? ""),
+    attachment: normalizeCompletionReplyAttachment(draft.attachment),
     mode: normalizeReplyMode(draft.mode),
     notice: normalizeClientText(draft.notice),
     error: normalizeClientText(draft.error),
@@ -815,13 +883,22 @@ function setCompletionReplyDraft(token, partialDraft) {
   if (!token) {
     return;
   }
+  const previousStoredDraft = state.completionReplyDrafts?.[token] || {};
+  const previousAttachment = normalizeCompletionReplyAttachment(previousStoredDraft.attachment);
   const nextDraft = {
     ...getCompletionReplyDraft(token),
     ...(partialDraft || {}),
   };
+  const nextAttachment = Object.prototype.hasOwnProperty.call(partialDraft || {}, "attachment")
+    ? normalizeCompletionReplyAttachment(partialDraft?.attachment)
+    : normalizeCompletionReplyAttachment(nextDraft.attachment);
+  if (previousAttachment?.previewUrl && previousAttachment.previewUrl !== nextAttachment?.previewUrl) {
+    releaseCompletionReplyAttachment(previousAttachment);
+  }
   state.completionReplyDrafts[token] = {
     text: String(nextDraft.text ?? ""),
     sentText: normalizeClientText(nextDraft.sentText ?? ""),
+    attachment: nextAttachment,
     mode: normalizeReplyMode(nextDraft.mode),
     notice: normalizeClientText(nextDraft.notice),
     error: normalizeClientText(nextDraft.error),
@@ -836,9 +913,16 @@ function clearCompletionReplyDraft(token) {
   if (!token || !state.completionReplyDrafts?.[token]) {
     return;
   }
+  releaseCompletionReplyAttachment(state.completionReplyDrafts[token]?.attachment);
   delete state.completionReplyDrafts[token];
 }
 
+function clearAllCompletionReplyDrafts() {
+  for (const token of Object.keys(state.completionReplyDrafts || {})) {
+    clearCompletionReplyDraft(token);
+  }
+}
+
 function syncCompletionReplyComposerLiveState(replyForm, draft) {
   if (!replyForm) {
     return;
@@ -2210,6 +2294,8 @@ function renderCompletionReplyComposer(detail, options = {}) {
   const warningTimestamp = draft.warning?.createdAtMs ? formatTimelineTimestamp(draft.warning.createdAtMs) : "";
   const showCollapsedState =
     draft.collapsedAfterSend && Boolean(draft.notice) && !draft.error && !draft.warning && !draft.sending;
+  const attachmentName = draft.attachment?.name ? escapeHtml(draft.attachment.name) : "";
+  const attachmentPreviewUrl = draft.attachment?.previewUrl ? escapeHtml(draft.attachment.previewUrl) : "";
 
   return `
     <section class="detail-card detail-card--reply ${options.mobile ? "detail-card--mobile" : ""}">
@@ -2275,6 +2361,55 @@ function renderCompletionReplyComposer(detail, options = {}) {
                     data-reply-token="${escapeHtml(detail.token)}"
                   >${escapeHtml(draft.text)}</textarea>
                 </label>
+                ${
+                  detail.reply?.supportsImages
+                    ? `
+                      <div class="reply-attachment-field">
+                        <div class="reply-attachment-field__header">
+                          <span class="field-label">${escapeHtml(L("reply.imageLabel"))}</span>
+                          ${
+                            draft.attachment
+                              ? `
+                                <button
+                                  class="secondary secondary--compact"
+                                  type="button"
+                                  data-reply-image-remove
+                                  data-reply-token="${escapeHtml(detail.token)}"
+                                >
+                                  ${escapeHtml(L("reply.imageRemove"))}
+                                </button>
+                              `
+                              : ""
+                          }
+                        </div>
+                        <label class="reply-attachment-picker">
+                          <input
+                            class="reply-attachment-picker__input"
+                            type="file"
+                            accept="image/*"
+                            data-reply-image-input
+                            data-reply-token="${escapeHtml(detail.token)}"
+                          >
+                          <span class="reply-attachment-picker__label">${escapeHtml(L(draft.attachment ? "reply.imageReplace" : "reply.imageAdd"))}</span>
+                          <span class="reply-attachment-picker__hint">${escapeHtml(L("reply.imageHint"))}</span>
+                        </label>
+                        ${
+                          draft.attachment
+                            ? `
+                              <div class="reply-image-preview">
+                                <img class="reply-image-preview__image" src="${attachmentPreviewUrl}" alt="${attachmentName}">
+                                <div class="reply-image-preview__copy">
+                                  <p class="reply-image-preview__name">${attachmentName}</p>
+                                  <p class="reply-image-preview__meta">${escapeHtml(L("reply.imageAttached"))}</p>
+                                </div>
+                              </div>
+                            `
+                            : ""
+                        }
+                      </div>
+                    `
+                    : ""
+                }
                 ${
                   detail.reply?.supportsPlanMode
                     ? `
@@ -2841,6 +2976,46 @@ function bindShellInteractions() {
     });
   }
 
+  for (const input of document.querySelectorAll("[data-reply-image-input][data-reply-token]")) {
+    input.addEventListener("change", async () => {
+      const token = input.dataset.replyToken || "";
+      const [file] = Array.from(input.files || []);
+      const nextAttachment = createCompletionReplyAttachment(file);
+      if (!nextAttachment && file) {
+        setCompletionReplyDraft(token, {
+          error: L("error.completionReplyImageInvalidType"),
+          notice: "",
+          warning: null,
+          confirmOverride: false,
+        });
+        await renderShell();
+        return;
+      }
+      setCompletionReplyDraft(token, {
+        attachment: nextAttachment,
+        notice: "",
+        error: "",
+        warning: null,
+        confirmOverride: false,
+      });
+      await renderShell();
+    });
+  }
+
+  for (const button of document.querySelectorAll("[data-reply-image-remove][data-reply-token]")) {
+    button.addEventListener("click", async () => {
+      const token = button.dataset.replyToken || "";
+      setCompletionReplyDraft(token, {
+        attachment: null,
+        notice: "",
+        error: "",
+        warning: null,
+        confirmOverride: false,
+      });
+      await renderShell();
+    });
+  }
+
   for (const button of document.querySelectorAll("[data-open-logout-confirm]")) {
     button.addEventListener("click", async () => {
       state.logoutConfirmOpen = true;
@@ -3010,14 +3185,18 @@ function bindShellInteractions() {
       await renderShell();
 
       try {
-        await apiPost(`/api/items/completion/${encodeURIComponent(token)}/reply`, {
-          text,
-          planMode: draft.mode === "plan",
-          force: draft.confirmOverride === true,
-        });
+        const requestBody = new FormData();
+        requestBody.set("text", text);
+        requestBody.set("planMode", draft.mode === "plan" ? "true" : "false");
+        requestBody.set("force", draft.confirmOverride === true ? "true" : "false");
+        if (COMPLETION_REPLY_IMAGE_SUPPORT && draft.attachment?.file) {
+          requestBody.append("image", draft.attachment.file, draft.attachment.name || draft.attachment.file.name);
+        }
+        await apiPost(`/api/items/completion/${encodeURIComponent(token)}/reply`, requestBody);
         setCompletionReplyDraft(token, {
           text: "",
           sentText: text,
+          attachment: null,
           mode: draft.mode,
           sending: false,
           error: "",
@@ -3032,6 +3211,7 @@ function bindShellInteractions() {
           setCompletionReplyDraft(token, {
             text,
             sentText: "",
+            attachment: draft.attachment,
             mode: draft.mode,
             sending: false,
             notice: "",
@@ -3046,6 +3226,7 @@ function bindShellInteractions() {
         setCompletionReplyDraft(token, {
           text,
           sentText: "",
+          attachment: draft.attachment,
           mode: draft.mode,
           sending: false,
           notice: "",
@@ -3759,14 +3940,19 @@ async function apiGet(url) {
 }
 
 async function apiPost(url, body) {
+  const isFormDataBody = typeof FormData !== "undefined" && body instanceof FormData;
   const response = await fetch(url, {
     method: "POST",
     credentials: "same-origin",
-    headers: {
-      "Content-Type": "application/json",
-      Accept: "application/json",
-    },
-    body: JSON.stringify(body || {}),
+    headers: isFormDataBody
+      ? {
+          Accept: "application/json",
+        }
+      : {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+    body: isFormDataBody ? body : JSON.stringify(body || {}),
   });
   if (!response.ok) {
     const errorInfo = await readError(response);
@@ -3809,6 +3995,11 @@ function localizeApiError(value) {
     "completion-reply-unavailable": "error.completionReplyUnavailable",
     "completion-reply-thread-advanced": "error.completionReplyThreadAdvanced",
     "completion-reply-empty": "error.completionReplyEmpty",
+    "completion-reply-image-invalid-type": "error.completionReplyImageInvalidType",
+    "completion-reply-image-too-large": "error.completionReplyImageTooLarge",
+    "completion-reply-image-limit": "error.completionReplyImageLimit",
+    "completion-reply-image-invalid-upload": "error.completionReplyImageInvalidUpload",
+    "completion-reply-image-disabled": "error.completionReplyImageDisabled",
     "codex-ipc-not-connected": "error.codexIpcNotConnected",
     "approval-not-found": "error.approvalNotFound",
     "approval-already-handled": "error.approvalAlreadyHandled",
@@ -3883,12 +4074,23 @@ function syncPairingTokenState(pairToken) {
 }
 
 function desiredBootstrapPairingToken() {
-  if (state.session?.authenticated) {
+  if (state.session?.authenticated && !state.session?.temporaryPairing) {
     return "";
   }
   return initialPairToken;
 }
 
+function shouldAutoPairFromBootstrapToken() {
+  if (!initialPairToken) {
+    return false;
+  }
+  return true;
+}
+
+function shouldUseTemporaryBootstrapPairing() {
+  return Boolean(initialPairToken) && !isStandaloneMode() && isProbablySafari();
+}
+
 function urlBase64ToUint8Array(base64String) {
   const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
   const normalized = `${base64String}${padding}`.replace(/-/gu, "+").replace(/_/gu, "/");

package/web/i18n.js

@@ -70,6 +70,8 @@ const translations = {
     "pair.codeLabel": "Pairing code",
     "pair.codePlaceholder": "Enter the pairing code",
     "pair.connect": "Connect this iPhone",
+    "pair.installFromHomeScreen":
+      "This pairing link is being kept for the Home Screen app. Add viveworker to your Home Screen from Safari, then open the new icon to finish pairing there.",
     "pair.helperTitle": "Add to Home Screen",
     "pair.helperCopy": "Install viveworker for the best mobile layout and Web Push support.",
     "banner.install.title": "Add viveworker to your Home Screen",
@@ -112,6 +114,12 @@ const translations = {
     "reply.copy": "Send a new message back into this Codex thread from the latest completed result.",
     "reply.fieldLabel": "Message",
     "reply.placeholder": "Ask Codex to continue, refine the result, or try a different approach.",
+    "reply.imageLabel": "Image",
+    "reply.imageAdd": "Add image",
+    "reply.imageReplace": "Replace image",
+    "reply.imageRemove": "Remove",
+    "reply.imageHint": "Attach one image from your iPhone and send it together with your message.",
+    "reply.imageAttached": "Attached image",
     "reply.send": "Send to Codex",
     "reply.sendConfirm": "Send anyway",
     "reply.sendAnother": "Send another message",
@@ -283,6 +291,11 @@ const translations = {
     "error.completionReplyUnavailable": "This completed item can no longer send a follow-up.",
     "error.completionReplyThreadAdvanced": "This thread already has newer messages.",
     "error.completionReplyEmpty": "Enter a message before sending it.",
+    "error.completionReplyImageInvalidType": "Choose an image file to attach.",
+    "error.completionReplyImageTooLarge": "That image is too large to send from this reply screen.",
+    "error.completionReplyImageLimit": "Attach one image at a time for now.",
+    "error.completionReplyImageInvalidUpload": "That image could not be uploaded.",
+    "error.completionReplyImageDisabled": "Image attachments are not available in this release.",
     "error.codexIpcNotConnected": "Codex desktop is not connected right now.",
     "error.approvalNotFound": "This approval is no longer available.",
     "error.approvalAlreadyHandled": "This approval was already handled.",
@@ -394,6 +407,8 @@ const translations = {
     "logout.action.removeDevice": "Log out and remove this device",
     "cli.setup.warning.insecureHttpLan":
       "Warning: insecure LAN HTTP is enabled. Session and device cookies can be exposed on the local network.",
+    "cli.setup.warning.stalePairingServer":
+      "Warning: viveworker is responding on port {port}, but it is still serving older pairing credentials. Another bridge process may still own this port. Stop the older instance, then rerun setup or start.",
     "cli.setup.qrPairing": "Pairing QR:",
     "cli.setup.qrCaDownload": "rootCA.pem download QR (IP):",
     "cli.setup.prompt.continueToApp": "Press Enter to continue to the viveworker app URL.",
@@ -509,6 +524,8 @@ const translations = {
     "pair.codeLabel": "ペアリングコード",
     "pair.codePlaceholder": "ペアリングコードを入力",
     "pair.connect": "この iPhone を接続",
+    "pair.installFromHomeScreen":
+      "この pairing link はホーム画面アプリ用に温存されています。Safari から viveworker をホーム画面に追加し、新しいアイコンを開いてそこで pairing を完了してください。",
     "pair.helperTitle": "ホーム画面に追加",
     "pair.helperCopy": "モバイル表示と Web Push を最適に使うには viveworker をインストールしてください。",
     "banner.install.title": "viveworker をホーム画面に追加",
@@ -550,6 +567,12 @@ const translations = {
     "reply.copy": "この完了結果を見ながら、同じ Codex スレッドに新しいメッセージを送れます。",
     "reply.fieldLabel": "メッセージ",
     "reply.placeholder": "続きを依頼したり、結果の修正や別案を Codex に伝えます。",
+    "reply.imageLabel": "画像",
+    "reply.imageAdd": "画像を追加",
+    "reply.imageReplace": "画像を差し替え",
+    "reply.imageRemove": "削除",
+    "reply.imageHint": "iPhone の画像を 1 枚だけ添付して、メッセージと一緒に送れます。",
+    "reply.imageAttached": "添付した画像",
     "reply.send": "Codex に送信",
     "reply.sendConfirm": "それでも送信",
     "reply.sendAnother": "もう一度送る",
@@ -721,6 +744,11 @@ const translations = {
     "error.completionReplyUnavailable": "この完了項目には、もう返信できません。",
     "error.completionReplyThreadAdvanced": "このスレッドには、すでに新しいメッセージがあります。",
     "error.completionReplyEmpty": "送信前にメッセージを入力してください。",
+    "error.completionReplyImageInvalidType": "添付できるのは画像ファイルのみです。",
+    "error.completionReplyImageTooLarge": "この画面から送るには画像が大きすぎます。",
+    "error.completionReplyImageLimit": "いまは画像を 1 枚ずつ添付してください。",
+    "error.completionReplyImageInvalidUpload": "この画像はアップロードできませんでした。",
+    "error.completionReplyImageDisabled": "このリリースでは画像添付はまだ利用できません。",
     "error.codexIpcNotConnected": "いまは Codex desktop に接続できていません。",
     "error.approvalNotFound": "この承認はもう利用できません。",
     "error.approvalAlreadyHandled": "この承認はすでに処理済みです。",
@@ -832,6 +860,8 @@ const translations = {
     "logout.action.removeDevice": "ログアウトしてこの端末を削除",
     "cli.setup.warning.insecureHttpLan":
       "警告: insecure LAN HTTP が有効です。session / device cookie がローカルネットワーク上で露出する可能性があります。",
+    "cli.setup.warning.stalePairingServer":
+      "警告: port {port} の viveworker は応答していますが、古い pairing 情報を配信したままです。別の bridge process がこの port を使っている可能性があります。古い instance を停止してから setup または start をやり直してください。",
     "cli.setup.qrPairing": "Pairing QR:",
     "cli.setup.qrCaDownload": "rootCA.pem download QR (IP):",
     "cli.setup.prompt.continueToApp": "viveworker の接続先 URL を表示するには Enter を押してください。",

package/web/sw.js

@@ -1,4 +1,4 @@
-const CACHE_NAME = "viveworker-v2";
+const CACHE_NAME = "viveworker-v5";
 const APP_ASSETS = ["/app.css", "/app.js", "/i18n.js"];
 const APP_ROUTES = new Set(["/", "/app", "/app/"]);
 const CACHED_PATHS = new Set(APP_ASSETS);