fix(opencode): address final-review findings

Follow-ups from the branch-level code review.  All low-risk fixes that
came up during verification/review of the otherwise-ready feature.

- RemoteHost.launch_opencode: read the opencode server password from a
  mode-0600 file in the workdir via `$(cat ...)` rather than inlining
  it into the command string.  Previously any local user on the remote
  host could read the basic-auth password from the bash process's argv
  via `ps aux` during the launch window.  Env variables (asyncssh
  create_process env=) would be cleaner but OpenSSH's default
  AcceptEnv won't forward arbitrary names, so a mode-0600 file the
  command substitutes at exec time is the portable fix.

- RemoteHost.terminate_opencode(aggressive=True): use proc.kill()
  (SIGKILL) instead of proc.terminate() (SIGTERM).  The spec's
  cancellation path expects SIGKILL; with SIGTERM an opencode that
  blocks on shutdown would eat the 5-second shutdown grace period.
  LocalHost was already correct.

- LocalHost.tail_log / RemoteHost.tail_log: document why we use
  `tail -F -n +1` instead of the spec's `-n 0`.  Fresh workdir + race-
  free at-least-once delivery (an earlier `-n 0` attempt silently
  dropped log lines that opencode wrote between subprocess spawn and
  our tail subscribing).

- Remove unused `aiofiles>=23.0` dependency (the module docstring
  mentioned it but the implementation spawns a `tail` subprocess;
  aiofiles was never imported).  Update host.py's module docstring.

- AGENTS.md: add a "Where the fork lives" paragraph pointing at
  github.com/csillag/opencode #csillag/make-web-embeddable-in-iframes,
  the upstream PR anomalyco/opencode#23912, and the build command so
  someone picking up this branch cold can populate
  OPTIO_OPENCODE_BINARY_DIR without hunting for the right repo.

Deferred review items (no change in this commit): remote-mode
cancellation test (spec Section 9 coverage gap), routing install
stderr through ctx.report_progress (nice-to-have), cosmetic
file-touch idiom, demo-task inner.execute clarification, SFTP-over-
SSH retry path not exercised by tests, negative-cache comment
consolidation.

Author: csillag

packages/optio-opencode/AGENTS.md

@@ -88,6 +88,17 @@ This is a bridge feature for shipping an iframe-embeddability fork of
 opencode until those fixes land upstream; once upstream ships, the env
 var's only remaining use is pinning to a specific build.
 
+**Where the fork lives:** the patched binaries are built from
+<https://github.com/csillag/opencode> on branch
+`csillag/make-web-embeddable-in-iframes` — three small orthogonal
+patches (relative vite base, CSP `'unsafe-eval'`, `getCurrentUrl`
+honoring localStorage).  Upstream PR:
+<https://github.com/anomalyco/opencode/pull/23912>.  To populate
+`OPTIO_OPENCODE_BINARY_DIR`: check out that branch, run
+`bun install && bun run --cwd packages/opencode build`, and point the
+env var at the resulting `packages/opencode/dist/` directory (which
+contains per-target subdirs such as `opencode-linux-x64/bin/opencode`).
+
 ## Testing
 
 Unit + local integration: `pytest tests/` (needs MongoDB via Docker).

packages/optio-opencode/pyproject.toml

@@ -11,7 +11,6 @@ requires-python = ">=3.11"
 dependencies = [
     "optio-core",
     "asyncssh>=2.14",
-    "aiofiles>=23.0",
 ]
 
 [project.optional-dependencies]

packages/optio-opencode/src/optio_opencode/host.py

@@ -2,7 +2,7 @@
 
 Two concrete implementations:
 
-* ``LocalHost`` — the optio worker itself.  Uses asyncio subprocess + aiofiles.
+* ``LocalHost`` — the optio worker itself.  Uses asyncio subprocess.
 * ``RemoteHost`` — a remote machine reachable over SSH.  Uses asyncssh,
   multiplexing command exec + SFTP + local port forwarding over a single
   connection.
@@ -278,6 +278,14 @@ async def establish_tunnel(self, opencode_port: int) -> int:
 
     async def tail_log(self) -> AsyncIterator[str]:
         log_path = os.path.join(self.workdir, "optio.log")
+        # `-n +1` reads from line 1, not EOF.  The design spec suggested
+        # `-n 0` (EOF) to avoid reprocessing a truncated earlier run, but
+        # our workdir is always fresh (setup_workdir creates the log
+        # empty just before this) so there's nothing to reprocess, and
+        # `-n 0` has a race: lines written to the log before tail
+        # subscribes (e.g. opencode eagerly appending STATUS right after
+        # launch) are silently skipped.  `-n +1` + always-empty initial
+        # log gives us at-least-once delivery.
         self._tail_proc = await asyncio.create_subprocess_exec(
             "tail", "-F", "-n", "+1", log_path,
             stdout=asyncio.subprocess.PIPE,
@@ -495,17 +503,30 @@ async def launch_opencode(
         ready_timeout_s: float,
         extra_args: list[str] | None = None,
     ) -> LaunchedProcess:
-        assert self._conn is not None
+        assert self._conn is not None and self._sftp is not None
+        # Write the password to a mode-0600 file in the workdir and have
+        # the remote shell read it via command substitution at launch
+        # time.  Interpolating the literal password into the command
+        # string would leak it to any local user on the remote host who
+        # runs `ps` — the bash process executing our command has the full
+        # command line (including the password) in its argv.  With `$(cat
+        # .opencode-password)`, the command line only shows the expansion
+        # syntax, not the value; the file itself is readable only by our
+        # user.  The file is swept with the rest of the workdir on
+        # teardown.
+        pw_file = ".opencode-password"
+        await self.write_text(pw_file, password)
+        await self._conn.run(f"chmod 600 {self.workdir}/{pw_file}", check=True)
         cmd = (
             f"cd {self.workdir} && "
-            f"OPENCODE_SERVER_PASSWORD={password} "
+            f"OPENCODE_SERVER_PASSWORD=\"$(cat ./{pw_file})\" "
             f"BROWSER=true "
             # 2>&1 merges stderr into stdout because opencode prints the
             # "Web interface:" URL line via UI.println → stderr.
-            # Single-quote the command.  `$opencode` is safely substituted
-            # here (Python f-string) before the remote shell sees anything;
-            # the remote bash just sees the absolute path or the literal
-            # word "opencode".
+            # Single-quote the inner command.  `$opencode` is safely
+            # substituted here (Python f-string) before the remote shell
+            # sees anything; the remote bash just sees the absolute path
+            # or the literal word "opencode".
             f"bash -lc '{self._opencode_exec} web --port=0 --hostname=127.0.0.1 2>&1'"
         )
         self._launch_proc = await self._conn.create_process(cmd)
@@ -543,6 +564,8 @@ async def establish_tunnel(self, opencode_port: int) -> int:
     async def tail_log(self) -> AsyncIterator[str]:
         assert self._conn is not None
         log_path = f"{self.workdir}/optio.log"
+        # See LocalHost.tail_log for why `-n +1` rather than the spec's
+        # `-n 0`: fresh workdir + race-free at-least-once delivery.
         self._tail_proc = await self._conn.create_process(
             f"tail -F -n +1 {log_path}"
         )
@@ -564,7 +587,10 @@ async def terminate_opencode(
         if proc.returncode is not None:
             return
         if aggressive:
-            proc.terminate()
+            # Spec requires SIGKILL in the cancellation path — .terminate()
+            # sends SIGTERM, which opencode may handle and block on, blowing
+            # our shutdown grace budget.
+            proc.kill()
             # Best-effort: do not wait.
             return
         proc.terminate()