Distillation

Date: Sep 8, 2026

• 🟡 [requested-security-review] (03:08) User requested an independent, read-only security review of the exact current changes in /home/byk/Code/opencode-v2-pilot and every line of /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty.ts, verified against the current core implementation rather than cached reviews.
• 🟡 (03:08) User requested threat modeling for malicious model input; another Session in the same Location; symlink swaps; command/environment injection; permission asks, denials, hooks, and saved grants; stream EPIPE; regex DoS; memory/process exhaustion; stubborn descendants; unload/session deletion; and synthetic-output injection.
• 🟡 (03:08) User requested current file:line evidence, classifications of PASS, CONCERN, or MUST-FIX, and a final line exactly MERGE or DO-NOT-MERGE.
• 🔴 [enforced-read-only-review] (03:08) User directed that the security review must not edit files or start services.
• 🔴 (03:08) User stated runtime dependencies must flow from Schema to Core and Protocol, then from Core and Protocol to Server; Client runtime code may depend on Schema and Protocol but never Core or Server; sdk composes Client, Core, and Server.
• 🔴 (03:08) User requires always running bun typecheck from package directories such as packages/core, never invoking tsc directly.
• 🔴 (03:08) User requires tests to run from package directories such as packages/core, never from the repository root because of the do-not-run-tests-from-root guard.
• 🔴 (03:08) User requires never aliasing imports, including forms such as import { foo as bar } from "..." and resolve as pathResolve.
• 🔴 (03:08) User requires never using type-position import("...") references such as Schema.declare<import("@opencode/plugin/effect/plugin").Plugin["effect"]>; an aliased type import such as import type { Plugin as PluginDefinition } from "..." is permitted only as a last resort when names genuinely collide and no other option exists.
• 🔴 (03:08) User requires never using star imports, including import * as Foo from "..." and import type * as Foo from "...".
• 🔴 (03:08) User prefers importing a module’s own exported namespace by name when namespace-style access is needed, for example import { Project } from "@opencode/core/project" followed by Project.ID.
• 🔴 (03:08) User prefers dynamic imports for heavy modules used only in selected paths, with bindings destructured near the top of the narrowest scope; inline chains such as await import("./module").then((mod) => mod.value()) and (await import("./module")).value() should be avoided.
• 🔴 (03:08) User stated that after changing public Protocol or Server HttpApi, bun run generate must be run from packages/client; generated client files must not be edited directly.
• 🔴 (03:08) User stated the repository does not use Changesets and .changeset files must not be added.
• 🔴 (03:08) User stated the repository’s default branch is v2; branches/worktrees should default to v2 or origin/v2 if local v2 is unavailable, pull requests should target v2, and diffs should use v2 or origin/v2 because local main may not exist.
• 🔴 (03:08) User requires branch names of at most three hyphen-separated words, without slashes or type prefixes; examples given were session-recovery, fix-scroll-state, and regenerate-sdk.
• 🔴 (03:08) User requires conventional commit-style messages and PR titles in type(scope): summary form, with valid types feat, fix, docs, chore, refactor, and test.
• 🔴 (03:08) User stated the plugin package has Effect and Promise versions; every Effect domain must extend the corresponding Effect API client interface from @opencode/client/effect/api, must not redefine existing API-client functions, and should add only plugin-context-specific functions.
• 🔴 (03:08) User requires Effect-specific work to use current Effect v4 / effect-smol source rather than memory or older Effect v2/v3 examples; exact APIs should be checked in .opencode/references/effect-smol and nearby repository code.
• 🔴 (03:08) User prefers testEffect(...) from packages/opencode/test/lib/effect.ts for Effect services/layers/runtime/scoped-resource tests and it.live(...) for filesystem, git, HTTP servers, sockets, child processes, locks, real time, and other live platform behavior.
• 🔴 (03:08) Repository HEAD and comparison point were both reported as commit 2ac698d65aa4690a694307e9cbdf44537ea9a4fb.
• 🔴 (03:08) Repository status reported 6 modified tracked files: packages/core/src/plugin/host.ts, packages/core/test/plugin.test.ts, packages/core/test/plugin/host.ts, packages/plugin/src/effect/permission.ts, packages/plugin/src/promise/adapter.ts, and packages/plugin/src/promise/permission.ts; diffstat was 53 insertions across 6 files.
• 🔴 (03:08) Repository status also reported 3 untracked distribution directories: packages/cli/dist-v2-pilot-final/, packages/cli/dist-v2-pilot-next/, and packages/cli/dist-v2-pilot/; each contains cli-node-linux-x64/package.json and cli-node-linux-x64/bin/opencode2-node.
• 🔴 (03:09) Current change in packages/core/src/plugin/host.ts:386 exposes canonical permission assertions to plugins through permission.assert: permission.assert.
• 🔴 (03:09) Current change in packages/core/test/plugin/host.ts:108 adds the default test-host stub assert: () => Effect.die("unused permission.assert").
• 🔴 (03:09) Current change in packages/core/test/plugin.test.ts adds the test it.effect("exposes canonical permission assertions to Promise plugins", ...); the Promise plugin promise-permission calls ctx.permission.assert(...) with Session ID ses_plugin_permission, action shell, resource "'true'", and tool source IDs msg_plugin_permission and call_plugin_permission, then verifies activation status is active.
• 🔴 (03:09) Current change in packages/plugin/src/effect/permission.ts adds PermissionAssertInput with sessionID: Session.ID, action: string, resources: ReadonlyArray<string>, optional save, optional metadata: Record<string, unknown>, optional source: Permission.Source, and optional agent: Agent.ID; PermissionDomain.assert returns Effect.Effect<void, unknown>.
• 🔴 (03:09) Current change in packages/plugin/src/promise/permission.ts adds the same PermissionAssertInput shape, with PermissionDomain.assert returning Promise<void>.
• 🔴 (03:09) Current change in packages/plugin/src/promise/adapter.ts adapts Promise permission assertions using assert: (input) => run(host.permission.assert(input)).
• 🔴 (03:09) Current core implementation declares permission assertion in packages/core/src/permission.ts:105 as (input: AssertInput) => Effect.Effect<void, Error | SessionErrors.NotFoundError> and defines it with Effect.fn("Permission.assert") near line 221.
• 🔴 (03:09) /home/byk/.local/share/opencode-v2-pilot/config/opencode/plugins/pty.ts defines limits: MAX_BUFFER_SIZE = 1_000_000, MAX_SESSIONS = 25, MAX_SESSIONS_PER_OWNER = 5, DEFAULT_READ_LIMIT = 500, MAX_READ_LIMIT = 2_000, MAX_READ_OFFSET = 10_000, MAX_LINE_LENGTH = 2_000, MAX_PATTERN_LENGTH = 500, MAX_WRITE_SIZE = 65_536, MAX_TIMEOUT_SECONDS = 2_147_483, and KILL_GRACE_MS = 1_000.
• 🔴 (03:09) pty.ts:20-26 supplies child processes a fixed environment containing HOME from the parent or /home/byk, LANG from the parent or C.UTF-8, PATH=/usr/bin:/bin, SHELL=/bin/sh, and TERM=xterm-256color.
• 🔴 (03:09) pty.ts:137-339 registers tools pty_spawn, pty_write, pty_read, pty_list, and pty_kill; spawn, write, and kill declare permission "shell", while read and list do not.
• 🔴 (03:09) pty.ts:145-158 authorizes the requested command/workdir before enforcing per-owner and Location session limits, then runs /usr/bin/script with arguments ["-qefc", shellCommand(input.command, input.args), "/dev/null"], cwd set to the authorized directory, detached: true, and env: FIXED_ENV.
• 🔴 (03:09) pty.ts:146-152 limits each parent Session to 5 PTYs, removing the first exited or killed PTY when at the owner limit, and limits the Location to 25 retained PTYs.
• 🔴 (03:09) pty.ts:153 generates PTY IDs as pty_ plus the first 8 hexadecimal characters of a hyphen-stripped crypto.randomUUID().
• 🔴 (03:09) pty.ts:159-198 captures stdout/stderr during spawn and thereafter retains only the trailing MAX_BUFFER_SIZE characters; process error messages are appended to the same bounded buffer.
• 🔴 (03:09) pty.ts:199-225 marks a closing PTY as killed if it was killing, otherwise exited; records exit code/signal; and, when notifyOnExit is true, sends a synthetic steer to the owning Session containing <pty_exited>, ID, truncated description, exit code, timeout data, line count, and a last line truncated to 200 characters.
• 🔴 (03:09) pty.ts:227-235 implements optional timeout termination: when a running session reaches timeoutSeconds, it sets timedOut = true, changes status to killing, invokes terminate(session), logs failures, and unreferences object-form timers.
• 🔴 (03:09) pty.ts:268-272 restricts pty_write to the owning Session, requires status running, decodes supported escapes, and writes to child stdin with callback-based error propagation.
• 🔴 (03:09) pty.ts:283-303 restricts pty_read to the owning Session, paginates either plain lines or regex matches, truncates each emitted line to 2,000 characters, and wraps output in <pty_output ...> markup containing unescaped session status and optional pattern attributes.
• 🔴 (03:09) pty.ts:313-317 makes pty_list return only sessions whose parentSessionID matches the calling Session.
• 🔴 (03:09) pty.ts:327-336 restricts pty_kill to the owning Session; cleanup: true terminates, deletes, and clears buffered output, while normal kill terminates a running process but retains the session.
• 🔴 (03:09) pty.ts:341-355 subscribes to session.deleted, removes every PTY owned by the deleted Session, aborts the subscription on plugin unload, and removes all retained sessions during unload.
• 🔴 (03:09) pty.ts:363-366 enforces ownership in requireSession(...) by rejecting absent PTY IDs and PTYs whose parentSessionID differs from the caller’s Session ID.
• 🔴 (03:09) pty.ts:404-413 decodes only \xNN, \uNNNN, \n, \r, \t, and \\ escape forms.
• 🔴 (03:09) pty.ts:415-417 constructs shell command text by single-quoting the executable and every argument and replacing embedded single quotes with the shell sequence '\\''.
• 🔴 (03:09) pty.ts:419-440 terminates the detached process group via process.kill(-session.pid, signal), ignores ESRCH, sends SIGTERM, waits up to 1,000 ms for session.closed, sends SIGKILL if still open, then waits indefinitely for session.closed; concurrent termination calls reuse session.terminate.
• 🔴 (03:09) pty.ts:443-474 canonicalizes both requested workdir and project directory with realpath; requests external_directory permission when the canonical workdir is outside the canonical project; requests shell permission with the fully quoted command resource and save: [resource]; then re-runs realpath(workdir), rejects a changed canonical target, verifies it is a directory with stat(current).isDirectory(), and returns the earlier canonical directory.
• 🔴 (03:09) pty.ts:476-514 delegates regex matching to /usr/bin/grep with -a, -m <limit>, -nE, optional -i, and --; kills grep after 250 ms, bounds collected stdout to MAX_BUFFER_SIZE * 2, bounds collected stderr to MAX_LINE_LENGTH, ignores stdin EPIPE, treats exit code 1 as no matches, and parses line:text output.