opensocrates 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to OpenSocrates are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-07-31
+
+### Added
+
+- Local Codex selector and runtime with a 30-second, no-retry, fail-open
+  execution contract.
+- An authored catalog of 48 reasoning systems with English and Korean
+  user-facing messages.
+- Evidence, completion, routing, privacy, trace, and host-contract validation.
+- Reproducible Python 3.12 builds, native `darwin-arm64` packaging, checksums,
+  SBOM generation, security scanning, and release gates.
+- GitHub Release and dependency-free Node.js installation paths, including
+  `npx github:ParkerHwang/OpenSocrates#v1.0.0 install`.
+- The public `opensocrates` npm package for the shorter
+  `npx opensocrates@1.0.0 install` path.
+- English and Korean README files and standard open-source community health
+  documents.
+
+### Security and privacy
+
+- The selector uses the existing local Codex OAuth session; no API key or
+  hosted OpenSocrates backend is required.
+- Temporary instruction artifacts contain authored OpenSocrates material only.
+- Installer downloads are checked against release and package-level SHA-256
+  manifests before installation.
+
+### Known limitations
+
+- The packaged runtime is validated only for Apple-silicon macOS.
+- Signing, notarization, clean-machine installation, and live host hook
+  delivery remain explicitly unvalidated.
+
+[1.0.0]: https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parker Hwang
+
+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.ko.md

@@ -0,0 +1,182 @@
+# OpenSocrates
+
+[English](README.md) | **한국어**
+
+[![CI](https://github.com/ParkerHwang/OpenSocrates/actions/workflows/ci.yml/badge.svg)](https://github.com/ParkerHwang/OpenSocrates/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opensocrates)](https://www.npmjs.com/package/opensocrates)
+[![Release](https://img.shields.io/github/v/release/ParkerHwang/OpenSocrates)](https://github.com/ParkerHwang/OpenSocrates/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+OpenSocrates는 AI 에이전트 호스트를 위한 로컬 추론 프레임워크입니다. 의도적인
+추론이 필요한 요청을 감지하고, 별도의 Codex 컨텍스트에서 적합한 추론 시스템을
+선택한 뒤, 저작된 이론과 예제를 활성 작업에 추가합니다. 단순한 사실 확인과
+기계적인 작업은 그대로 통과할 수 있습니다.
+
+버전 `1.0.0`에는 48개의 추론 시스템이 들어 있으며 Apple Silicon macOS
+(`darwin-arm64`)의 Codex Desktop과 Codex CLI를 지원합니다. 다른 플랫폼,
+바이너리 서명, 공증, 클린 머신 설치는 아직 검증됐다고 주장하지 않습니다.
+
+## 설치
+
+설치 전에 OAuth로 Codex에 로그인하고 `codex` 명령을 사용할 수 있는지
+확인하세요.
+
+### 방법 1: npm에서 npx로 설치
+
+Node.js 20 이상이 필요합니다. npm 패키지는 외부 의존성이 없는 작은 설치
+프로그램이며, 일치하는 패키지를 GitHub Releases에서 내려받아 검증합니다.
+
+```bash
+npx --yes opensocrates@1.0.0 install
+```
+
+라이프사이클 명령:
+
+```bash
+npx --yes opensocrates@1.0.0 status
+npx --yes opensocrates@1.0.0 update
+npx --yes opensocrates@1.0.0 remove
+```
+
+### 방법 2: GitHub에서 npx로 설치
+
+Node.js 20 이상이 필요합니다. npm 레지스트리에 별도 패키지를 게시하지 않아도
+태그가 고정된 GitHub 저장소에서 직접 설치합니다.
+
+```bash
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 install
+```
+
+라이프사이클 명령:
+
+```bash
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 status
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 update
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 remove
+```
+
+설치 프로그램은 일치하는 GitHub Release 자산을 내려받고 릴리스 체크섬과
+패키지 내부의 모든 체크섬을 검증한 다음, 현재 Codex 홈 아래의 비공개 관리형
+마켓플레이스에 등록합니다.
+
+### 방법 3: GitHub Releases에서 직접 다운로드
+
+[v1.0.0 릴리스](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0)에서
+`opensocrates.mjs`를 내려받은 뒤 실행합니다.
+
+```bash
+node opensocrates.mjs install
+```
+
+파일과 체크섬을 직접 내려받아 확인하려면:
+
+```bash
+curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip
+curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip.sha256
+shasum -a 256 -c opensocrates-1.0.0-codex-plugin.zip.sha256
+node opensocrates.mjs install \
+  --asset opensocrates-1.0.0-codex-plugin.zip \
+  --checksum opensocrates-1.0.0-codex-plugin.zip.sha256
+```
+
+### 방법 4: 소스에서 빌드해 설치
+
+[uv](https://docs.astral.sh/uv/)와 Python 3.12가 필요합니다.
+
+```bash
+git clone https://github.com/ParkerHwang/OpenSocrates.git
+cd OpenSocrates
+uv python install 3.12
+uv sync --locked --all-groups
+make release-check
+uv run --locked --no-sync python tools/codex_plugin.py install
+```
+
+`make release-check`는 네이티브 런타임과 설치 가능한 패키지를 로컬에서
+빌드합니다. 생성 파일은 Git에서 제외된 `build/`와 `dist/`에 기록됩니다.
+
+## 사용법
+
+Codex를 평소처럼 사용하세요. OpenSocrates는 제출된 각 프롬프트 전에 실행되며,
+요청에 판단, 해석, 진단, 설명, 계획, 근거 조정 또는 다른 구조적 추론 과정이
+필요할 때 개입할 수 있습니다. 개입 시 다음 순서로 동작합니다.
+
+1. 매번 새로운 임시 셀렉터 스레드를 사용합니다.
+2. 저작된 48개 시스템 카탈로그에서 적합한 시스템을 선택합니다.
+3. 선택된 전체 콘텐츠를 소유자 전용 임시 Markdown 파일에 기록합니다.
+4. 활성 작업에 해당 파일을 읽으라는 하나의 숨겨진 컨텍스트 메시지를
+   추가합니다.
+
+선택 수에는 고정 제한이 없습니다. 훅 메시지는 작게 유지하면서 선택된 이론과
+예제 전체는 압축하거나 자르지 않고 참조 파일에 보존합니다.
+
+셀렉터의 내부 제한 시간은 30초이며 재시도하지 않고 실패 시 통과합니다.
+타임아웃, SDK 오류, 잘못된 출력, 미개입 결정, 안전하지 않은 컨텍스트 또는
+사용할 수 없는 훅은 모두 주입 없이 끝나며 사용자의 작업을 차단하지 않습니다.
+
+제한된 트랜스크립트 컨텍스트 요청도 막으려면:
+
+```bash
+export OPENSOCRATES_SELECTOR_TRANSCRIPT_ACCESS=0
+```
+
+## 개인정보 보호와 보안
+
+OpenSocrates는 Codex 앱 서버와 사용자의 기존 Codex OAuth 세션을 통해 로컬에서
+실행됩니다. API 키가 필요 없고, 백엔드를 호스팅하지 않으며, 사용자가 요청한
+작업을 대신 실행하지 않고, 텔레메트리를 추가하지 않습니다.
+
+임시 instruction 파일에는 OpenSocrates가 저작한 콘텐츠만 들어갑니다. 원시
+프롬프트, 대화 기록, 워크스페이스 파일, 도구 데이터, OAuth 자격 증명과 셀렉터
+추론은 기록, 로그, 메트릭, 진단 또는 임시 instruction 파일에 저장되지
+않습니다. `Stop`에서 현재 turn 파일을, `SessionEnd`에서 남은 세션 파일을,
+`SessionStart`에서 24시간이 지난 비정상 종료 잔여 파일을 삭제합니다.
+
+취약점 신고 방법과 현재 지원 경계는 [SECURITY.md](SECURITY.md)를 확인하세요.
+
+## 개발
+
+소스 저장소에는 네이티브 바이너리와 중간 빌드 결과를 넣지 않습니다. 잠긴 개발
+환경을 설치하고 다음 검사를 실행합니다.
+
+```bash
+make bootstrap
+make format-check
+make lint
+make generated-check
+make content-check
+make docs-check
+make security-scan
+make smoke
+npm test
+npm pack --dry-run
+make release-check
+```
+
+저장소 구조:
+
+| 경로 | 용도 |
+| --- | --- |
+| `src/opensocrates/` | Python 3.12 런타임과 셀렉터 소스 |
+| `content/` | 정책, 다국어 메시지, 추론 방법, 이론과 예제 |
+| `plugin-src/codex/` | Codex 플러그인 템플릿 |
+| `schemas/source/` | 정규 스키마 정의 |
+| `schemas/v1/` | 생성된 버전 고정 공개 스키마 |
+| `installer/` | 외부 의존성이 없는 Node.js GitHub/npx 설치 프로그램 |
+| `tools/` | 빌드, 검증, 라이프사이클, 보안, 릴리스 도구 |
+| `packaging/` | 네이티브 런처와 패키징 설정 |
+| `build/`, `dist/` | 로컬에서 생성되어 릴리스 자산으로 게시되는 파일 |
+
+생성된 스키마와 컴파일된 콘텐츠는 정규 소스와 생성기를 통해 변경해야 합니다.
+릴리스 바이너리는 Git 이력이 아니라 GitHub Releases에 둡니다.
+
+## 기여
+
+기여를 환영합니다. Pull Request를 열기 전에 [CONTRIBUTING.md](CONTRIBUTING.md)를
+읽고, 버그와 기능 요청에는 이슈 템플릿을 사용하세요. 이 프로젝트는
+[행동 강령](CODE_OF_CONDUCT.md)을 따릅니다.
+
+## 라이선스
+
+OpenSocrates는 [MIT 라이선스](LICENSE)로 배포됩니다. 저작권 및 라이선스 고지를
+유지하면 사용, 수정, 배포, 재라이선스와 판매가 가능합니다.

package/README.md

@@ -0,0 +1,193 @@
+# OpenSocrates
+
+**English** | [한국어](README.ko.md)
+
+[![CI](https://github.com/ParkerHwang/OpenSocrates/actions/workflows/ci.yml/badge.svg)](https://github.com/ParkerHwang/OpenSocrates/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/opensocrates)](https://www.npmjs.com/package/opensocrates)
+[![Release](https://img.shields.io/github/v/release/ParkerHwang/OpenSocrates)](https://github.com/ParkerHwang/OpenSocrates/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+OpenSocrates is a local reasoning framework for AI-agent hosts. It detects
+requests that benefit from deliberate reasoning, selects relevant reasoning
+systems in a separate Codex context, and adds their authored theory and
+examples to the active task. Straightforward factual and mechanical work can
+pass through unchanged.
+
+Version `1.0.0` includes 48 reasoning systems and supports Codex Desktop and
+Codex CLI on Apple-silicon macOS (`darwin-arm64`). Other platforms, binary
+signing, notarization, and clean-machine installation are not yet claimed as
+validated.
+
+## Install
+
+Before installing, sign in to Codex with OAuth and make sure the `codex`
+command is available.
+
+### Option 1: npx from npm
+
+Requires Node.js 20 or later. The npm package is a small, dependency-free
+installer; it downloads and verifies the matching package from GitHub
+Releases.
+
+```bash
+npx --yes opensocrates@1.0.0 install
+```
+
+Lifecycle commands:
+
+```bash
+npx --yes opensocrates@1.0.0 status
+npx --yes opensocrates@1.0.0 update
+npx --yes opensocrates@1.0.0 remove
+```
+
+### Option 2: npx from GitHub
+
+Requires Node.js 20 or later. This command installs directly from the tagged
+GitHub repository and remains available without the npm registry.
+
+```bash
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 install
+```
+
+Lifecycle commands:
+
+```bash
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 status
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 update
+npx --yes github:ParkerHwang/OpenSocrates#v1.0.0 remove
+```
+
+The installer downloads the matching GitHub Release asset, verifies both the
+release checksum and every checksum inside the package, and then registers a
+private managed marketplace under the current Codex home.
+
+### Option 3: download from GitHub Releases
+
+Download `opensocrates.mjs` from the
+[v1.0.0 release](https://github.com/ParkerHwang/OpenSocrates/releases/tag/v1.0.0),
+then run:
+
+```bash
+node opensocrates.mjs install
+```
+
+For a fully manual download and checksum check:
+
+```bash
+curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip
+curl -fLO https://github.com/ParkerHwang/OpenSocrates/releases/download/v1.0.0/opensocrates-1.0.0-codex-plugin.zip.sha256
+shasum -a 256 -c opensocrates-1.0.0-codex-plugin.zip.sha256
+node opensocrates.mjs install \
+  --asset opensocrates-1.0.0-codex-plugin.zip \
+  --checksum opensocrates-1.0.0-codex-plugin.zip.sha256
+```
+
+### Option 4: build and install from source
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.12.
+
+```bash
+git clone https://github.com/ParkerHwang/OpenSocrates.git
+cd OpenSocrates
+uv python install 3.12
+uv sync --locked --all-groups
+make release-check
+uv run --locked --no-sync python tools/codex_plugin.py install
+```
+
+`make release-check` builds the native runtime and installable package locally.
+Generated files are written to ignored `build/` and `dist/` directories.
+
+## Use
+
+Use Codex normally. Before each submitted prompt, OpenSocrates may intervene
+when the request needs judgment, interpretation, diagnosis, explanation,
+planning, evidence reconciliation, or another structured reasoning process.
+When it intervenes, it:
+
+1. uses a fresh, ephemeral selector thread;
+2. chooses from the authored 48-system catalog;
+3. writes the complete selected content to an owner-only temporary Markdown
+   file; and
+4. adds one hidden context message telling the active task to read that file.
+
+There is no fixed selection-count limit. The hook message stays small while
+the full selected theory and examples remain uncompressed in the referenced
+file.
+
+The selector has a 30-second internal deadline, does not retry, and fails open.
+A timeout, SDK error, invalid output, non-intervention decision, unsafe
+context, or unavailable hook produces no injection and does not block the
+user's task.
+
+To prevent the selector from requesting bounded transcript context:
+
+```bash
+export OPENSOCRATES_SELECTOR_TRANSCRIPT_ACCESS=0
+```
+
+## Privacy and security
+
+OpenSocrates runs locally through the Codex app-server and the user's existing
+Codex OAuth session. It does not require an API key, host a backend, execute
+the user's requested task, or add telemetry.
+
+Temporary instruction files contain authored OpenSocrates content only. Raw
+prompts, transcripts, workspace files, tool data, OAuth credentials, and
+selector reasoning are not written to records, logs, metrics, diagnostics, or
+temporary instruction files. Turn files are removed on `Stop`, remaining
+session files on `SessionEnd`, and crash leftovers older than 24 hours on
+`SessionStart`.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and the current
+support boundary.
+
+## Develop
+
+The source repository intentionally excludes native binaries and intermediate
+build output. Install the locked development environment and run:
+
+```bash
+make bootstrap
+make format-check
+make lint
+make generated-check
+make content-check
+make docs-check
+make security-scan
+make smoke
+npm test
+npm pack --dry-run
+make release-check
+```
+
+Repository layout:
+
+| Path | Purpose |
+| --- | --- |
+| `src/opensocrates/` | Python 3.12 runtime and selector source |
+| `content/` | Policies, localized messages, methods, theory, and examples |
+| `plugin-src/codex/` | Codex plugin templates |
+| `schemas/source/` | Canonical schema definitions |
+| `schemas/v1/` | Generated, versioned public schemas |
+| `installer/` | Dependency-free Node.js GitHub/npx installer |
+| `tools/` | Build, validation, lifecycle, security, and release tools |
+| `packaging/` | Native launcher and packaging configuration |
+| `build/`, `dist/` | Generated locally and published as release assets |
+
+Generated schemas and compiled content must be changed through their canonical
+sources and generators. Release binaries belong in GitHub Releases, not in the
+Git history.
+
+## Contributing
+
+Contributions are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before
+opening a pull request, and use the issue templates for bugs and feature
+requests. The project follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+OpenSocrates is available under the [MIT License](LICENSE). You may use,
+modify, distribute, sublicense, and sell copies, provided the copyright and
+license notice are preserved.

package/SECURITY.md

@@ -0,0 +1,47 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest `1.x` release. Pre-1.0 builds are
+not supported.
+
+| Version | Supported |
+| --- | --- |
+| 1.x | Yes |
+| < 1.0 | No |
+
+## Report a vulnerability
+
+Do not publish credentials, private prompts, transcripts, workspace data, or
+exploit details in a public issue.
+
+Use GitHub's
+[private vulnerability reporting](https://github.com/ParkerHwang/OpenSocrates/security/advisories/new)
+to send a confidential report. Include:
+
+- the affected version and platform;
+- the smallest reproducible example;
+- expected and observed impact;
+- whether credentials or private user data may be exposed;
+- any suggested mitigation.
+
+If private reporting is unavailable, open a public issue requesting a private
+contact channel without including vulnerability details.
+
+Reports are reviewed as maintainer capacity allows. Acknowledgement,
+assessment, remediation, and disclosure timing depend on reproducibility,
+severity, and the availability of a safe fix.
+
+## Security boundary
+
+OpenSocrates 1.0:
+
+- runs locally through Codex and uses the user's existing OAuth session;
+- does not require or store an OpenAI API key;
+- does not host an OpenSocrates backend or add telemetry;
+- verifies downloadable packages with SHA-256 release and package manifests;
+- fails open when the selector cannot safely complete.
+
+Signing, notarization, clean-machine installation, platforms other than
+`darwin-arm64`, and actual host hook delivery are not claimed as validated.
+See the release limitations file for the complete measured boundary.

package/VERSION

@@ -0,0 +1 @@
+1.0.0

package/installer/opensocrates.mjs

@@ -0,0 +1,736 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, realpathSync } from "node:fs";
+import {
+  access,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+
+export const PRODUCT_VERSION = "1.0.0";
+export const REPOSITORY = "ParkerHwang/OpenSocrates";
+export const MARKETPLACE_NAME = "opensocrates";
+export const PLUGIN_NAME = "opensocrates";
+export const PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
+export const ASSET_NAME = `opensocrates-${PRODUCT_VERSION}-codex-plugin.zip`;
+export const CHECKSUM_NAME = `${ASSET_NAME}.sha256`;
+
+const MARKER_NAME = ".opensocrates-managed.json";
+const MARKER = Object.freeze({
+  schemaVersion: 1,
+  marketplaceName: MARKETPLACE_NAME,
+  pluginName: PLUGIN_NAME,
+});
+const MARKETPLACE_RELATIVE = join(".agents", "plugins", "marketplace.json");
+const PLUGIN_RELATIVE = join("build", "generated", "plugins", "codex");
+const MAX_DOWNLOAD_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ARCHIVE_ENTRIES = 10_000;
+
+export class InstallerError extends Error {}
+
+function fail(message) {
+  throw new InstallerError(message);
+}
+
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function jsonEqual(left, right) {
+  const leftKeys = Object.keys(left).sort();
+  const rightKeys = Object.keys(right).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every((key, index) => key === rightKeys[index] && left[key] === right[key])
+  );
+}
+
+export function markerMatches(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    jsonEqual(value, MARKER)
+  );
+}
+
+export function isSafeArchivePath(value) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.includes("\0") ||
+    value.includes("\\") ||
+    value.startsWith("/")
+  ) {
+    return false;
+  }
+  const candidate = value.endsWith("/") ? value.slice(0, -1) : value;
+  if (candidate.length === 0) {
+    return false;
+  }
+  return candidate.split("/").every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+
+export function parseChecksumText(text, expectedName = ASSET_NAME) {
+  const candidates = String(text)
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  for (const line of candidates) {
+    const match = line.match(/^([a-fA-F0-9]{64})(?:\s+[*]?(.+))?$/u);
+    if (!match) {
+      continue;
+    }
+    const namedFile = match[2]?.trim();
+    if (namedFile && basename(namedFile) !== expectedName) {
+      continue;
+    }
+    return match[1].toLowerCase();
+  }
+  fail(`checksum file does not contain a SHA-256 entry for ${expectedName}`);
+}
+
+export function parseCli(argv) {
+  const actions = new Set(["install", "status", "update", "remove", "verify", "help"]);
+  const args = [...argv];
+  let action = "install";
+  if (args[0] && !args[0].startsWith("-")) {
+    action = args.shift();
+  }
+  if (!actions.has(action)) {
+    fail(`unknown action ${JSON.stringify(action)}`);
+  }
+  const options = { action, asset: null, checksum: null };
+  while (args.length > 0) {
+    const flag = args.shift();
+    if (flag === "--help" || flag === "-h") {
+      options.action = "help";
+      continue;
+    }
+    if (flag !== "--asset" && flag !== "--checksum") {
+      fail(`unknown option ${JSON.stringify(flag)}`);
+    }
+    const value = args.shift();
+    if (!value || value.startsWith("-")) {
+      fail(`${flag} requires a file path`);
+    }
+    options[flag === "--asset" ? "asset" : "checksum"] = resolve(value);
+  }
+  if ((options.asset === null) !== (options.checksum === null)) {
+    fail("--asset and --checksum must be supplied together");
+  }
+  if (["status", "remove", "help"].includes(options.action) && options.asset !== null) {
+    fail(`${options.action} does not accept --asset or --checksum`);
+  }
+  return options;
+}
+
+function showHelp() {
+  console.log(`OpenSocrates ${PRODUCT_VERSION}
+
+Usage:
+  opensocrates install [--asset ZIP --checksum SHA256]
+  opensocrates status
+  opensocrates update [--asset ZIP --checksum SHA256]
+  opensocrates remove
+  opensocrates verify [--asset ZIP --checksum SHA256]
+
+Without --asset, install, update, and verify download the v${PRODUCT_VERSION}
+package and checksum from GitHub Releases.
+`);
+}
+
+function managedPaths() {
+  const configured = process.env.CODEX_HOME;
+  const codexHome = resolve(configured ? configured : join(homedir(), ".codex"));
+  const root = join(codexHome, "managed-marketplaces", MARKETPLACE_NAME);
+  return {
+    codexHome,
+    root,
+    parent: dirname(root),
+    marker: join(root, MARKER_NAME),
+    marketplace: join(root, MARKETPLACE_RELATIVE),
+    plugin: join(root, PLUGIN_RELATIVE),
+  };
+}
+
+function codexBinary() {
+  return process.env.CODEX_BIN || "codex";
+}
+
+function run(command, args, { allowFailure = false } = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    env: process.env,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error) {
+    if (allowFailure) {
+      return result;
+    }
+    fail(`could not run ${command}: ${result.error.message}`);
+  }
+  if (result.status !== 0 && !allowFailure) {
+    const detail = result.stderr?.trim() || result.stdout?.trim() || `exit ${result.status}`;
+    fail(`${command} ${args.join(" ")} failed: ${detail}`);
+  }
+  return result;
+}
+
+function runCodexJson(args) {
+  const result = run(codexBinary(), args);
+  try {
+    const payload = JSON.parse(result.stdout);
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+      fail("Codex returned a non-object JSON value");
+    }
+    return payload;
+  } catch (error) {
+    if (error instanceof InstallerError) {
+      throw error;
+    }
+    fail(`Codex returned invalid JSON for ${args.join(" ")}: ${error.message}`);
+  }
+}
+
+function requireCodex() {
+  run(codexBinary(), ["--version"]);
+}
+
+function marketplaceEntry() {
+  const payload = runCodexJson(["plugin", "marketplace", "list", "--json"]);
+  const entries = payload.marketplaces;
+  if (!Array.isArray(entries)) {
+    fail("Codex marketplace list returned an unexpected schema");
+  }
+  const matches = entries.filter((entry) => entry?.name === MARKETPLACE_NAME);
+  if (matches.length > 1) {
+    fail(`Codex reported duplicate marketplaces named ${MARKETPLACE_NAME}`);
+  }
+  return matches[0] ?? null;
+}
+
+function pluginState() {
+  const payload = runCodexJson([
+    "plugin",
+    "list",
+    "--marketplace",
+    MARKETPLACE_NAME,
+    "--available",
+    "--json",
+  ]);
+  const installed = Array.isArray(payload.installed) ? payload.installed : null;
+  const available = Array.isArray(payload.available) ? payload.available : null;
+  if (installed === null || available === null) {
+    fail("Codex plugin list returned an unexpected schema");
+  }
+  const installedMatches = installed.filter((entry) => entry?.pluginId === PLUGIN_ID);
+  const availableMatches = available.filter((entry) => entry?.pluginId === PLUGIN_ID);
+  if (installedMatches.length > 1 || availableMatches.length > 1) {
+    fail(`Codex reported duplicate entries for ${PLUGIN_ID}`);
+  }
+  if (installedMatches.length === 1) {
+    return { kind: "installed", version: installedMatches[0].version ?? null };
+  }
+  if (availableMatches.length === 1) {
+    return { kind: "available", version: availableMatches[0].version ?? null };
+  }
+  return { kind: "missing", version: null };
+}
+
+async function readJsonObject(target) {
+  let payload;
+  try {
+    payload = JSON.parse(await readFile(target, "utf8"));
+  } catch (error) {
+    fail(`cannot read valid JSON from ${target}: ${error.message}`);
+  }
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+    fail(`expected a JSON object in ${target}`);
+  }
+  return payload;
+}
+
+async function requireOwnedRoot(root) {
+  const info = await lstat(root);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    fail(`managed marketplace path is not an owned directory: ${root}`);
+  }
+  const marker = await readJsonObject(join(root, MARKER_NAME));
+  if (!markerMatches(marker)) {
+    fail(`managed marketplace path has no valid ownership marker: ${root}`);
+  }
+}
+
+async function sha256File(target) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(target)) {
+    hash.update(chunk);
+  }
+  return hash.digest("hex");
+}
+
+async function downloadFile(url, destination) {
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/octet-stream",
+      "user-agent": `OpenSocrates-installer/${PRODUCT_VERSION}`,
+    },
+    redirect: "follow",
+    signal: AbortSignal.timeout(15 * 60 * 1000),
+  });
+  if (!response.ok || response.body === null) {
+    fail(`download failed (${response.status}) for ${url}`);
+  }
+  const contentLength = Number(response.headers.get("content-length") ?? "0");
+  if (Number.isFinite(contentLength) && contentLength > MAX_DOWNLOAD_BYTES) {
+    fail(`download exceeds the ${MAX_DOWNLOAD_BYTES}-byte safety limit`);
+  }
+  await pipeline(Readable.fromWeb(response.body), createWriteStream(destination, { mode: 0o600 }));
+  const downloaded = (await stat(destination)).size;
+  if (downloaded === 0 || downloaded > MAX_DOWNLOAD_BYTES) {
+    fail(`downloaded file has an invalid size: ${downloaded} bytes`);
+  }
+}
+
+async function resolveAssetInputs(options, scratch) {
+  if (options.asset !== null) {
+    if (!(await exists(options.asset)) || !(await exists(options.checksum))) {
+      fail("the supplied asset or checksum file does not exist");
+    }
+    return { asset: options.asset, checksum: options.checksum };
+  }
+  const base = `https://github.com/${REPOSITORY}/releases/download/v${PRODUCT_VERSION}`;
+  const asset = join(scratch, ASSET_NAME);
+  const checksum = join(scratch, CHECKSUM_NAME);
+  console.log(`Downloading OpenSocrates ${PRODUCT_VERSION} from GitHub Releases...`);
+  await downloadFile(`${base}/${ASSET_NAME}`, asset);
+  await downloadFile(`${base}/${CHECKSUM_NAME}`, checksum);
+  return { asset, checksum };
+}
+
+async function verifyOuterChecksum(asset, checksum) {
+  const expected = parseChecksumText(await readFile(checksum, "utf8"));
+  const actual = await sha256File(asset);
+  if (actual !== expected) {
+    fail(`release checksum mismatch: expected ${expected}, got ${actual}`);
+  }
+}
+
+function archiveEntries(asset) {
+  const unzip = process.platform === "darwin" ? "/usr/bin/unzip" : "unzip";
+  const result = run(unzip, ["-Z1", asset]);
+  const entries = result.stdout.split(/\r?\n/u).filter(Boolean);
+  if (entries.length === 0 || entries.length > MAX_ARCHIVE_ENTRIES) {
+    fail(`archive contains an invalid number of entries: ${entries.length}`);
+  }
+  const unique = new Set();
+  for (const entry of entries) {
+    if (!isSafeArchivePath(entry)) {
+      fail(`archive contains an unsafe path: ${JSON.stringify(entry)}`);
+    }
+    if (unique.has(entry)) {
+      fail(`archive contains a duplicate path: ${entry}`);
+    }
+    unique.add(entry);
+  }
+  return entries;
+}
+
+async function extractArchive(asset, destination) {
+  archiveEntries(asset);
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  const unzip = process.platform === "darwin" ? "/usr/bin/unzip" : "unzip";
+  run(unzip, ["-q", asset, "-d", destination]);
+}
+
+async function walkFiles(root, current = root, output = []) {
+  const entries = await readdir(current, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolute = join(current, entry.name);
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink()) {
+      fail(`package contains a symbolic link: ${relative(root, absolute)}`);
+    }
+    if (info.isDirectory()) {
+      await walkFiles(root, absolute, output);
+    } else if (info.isFile()) {
+      output.push(relative(root, absolute).split(sep).join("/"));
+    } else {
+      fail(`package contains an unsupported filesystem entry: ${relative(root, absolute)}`);
+    }
+  }
+  return output;
+}
+
+async function verifyPackageChecksums(pluginRoot) {
+  const checksumPath = join(pluginRoot, "checksums.sha256");
+  const lines = (await readFile(checksumPath, "utf8"))
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const declared = new Set();
+  for (const line of lines) {
+    const match = line.match(/^([a-fA-F0-9]{64})\s+[*]?(.+)$/u);
+    if (!match) {
+      fail(`invalid package checksum line: ${line}`);
+    }
+    const expected = match[1].toLowerCase();
+    const item = match[2].trim();
+    if (!isSafeArchivePath(item) || item === "checksums.sha256" || declared.has(item)) {
+      fail(`invalid or duplicate package checksum path: ${item}`);
+    }
+    declared.add(item);
+    const target = join(pluginRoot, ...item.split("/"));
+    if (!(await exists(target))) {
+      fail(`package checksum references a missing file: ${item}`);
+    }
+    const actual = await sha256File(target);
+    if (actual !== expected) {
+      fail(`package checksum mismatch for ${item}`);
+    }
+  }
+  const actualFiles = new Set((await walkFiles(pluginRoot)).filter((item) => item !== "checksums.sha256"));
+  if (
+    actualFiles.size !== declared.size ||
+    [...actualFiles].some((item) => !declared.has(item))
+  ) {
+    fail("package checksum manifest does not cover the complete archive");
+  }
+  return declared.size;
+}
+
+async function verifyExtractedPackage(pluginRoot) {
+  const manifest = await readJsonObject(join(pluginRoot, ".codex-plugin", "plugin.json"));
+  if (manifest.name !== PLUGIN_NAME || manifest.version !== PRODUCT_VERSION) {
+    fail(
+      `plugin manifest mismatch: expected ${PLUGIN_NAME} ${PRODUCT_VERSION}, ` +
+        `got ${String(manifest.name)} ${String(manifest.version)}`,
+    );
+  }
+  const release = await readJsonObject(join(pluginRoot, "release-manifest.json"));
+  if (
+    release.product_version !== PRODUCT_VERSION ||
+    release.host !== "codex" ||
+    release.schema !== "opensocrates.plugin-release-manifest/1.0.0"
+  ) {
+    fail("package release manifest does not match this installer");
+  }
+  const runtime = join(
+    pluginRoot,
+    "runtime",
+    "darwin-arm64",
+    "opensocrates-runtime",
+    "opensocrates-runtime",
+  );
+  const runtimeInfo = await stat(runtime);
+  if (!runtimeInfo.isFile() || (runtimeInfo.mode & 0o111) === 0) {
+    fail("package is missing the executable darwin-arm64 runtime");
+  }
+  return verifyPackageChecksums(pluginRoot);
+}
+
+async function prepareVerifiedPackage(options) {
+  const scratch = await mkdtemp(join(tmpdir(), "opensocrates-install-"));
+  try {
+    const { asset, checksum } = await resolveAssetInputs(options, scratch);
+    await verifyOuterChecksum(asset, checksum);
+    const pluginRoot = join(scratch, "plugin");
+    await extractArchive(asset, pluginRoot);
+    const checkedFiles = await verifyExtractedPackage(pluginRoot);
+    return { scratch, pluginRoot, checkedFiles };
+  } catch (error) {
+    await rm(scratch, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function expectedMarketplace() {
+  return {
+    name: MARKETPLACE_NAME,
+    interface: { displayName: "OpenSocrates" },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: {
+          source: "local",
+          path: "./build/generated/plugins/codex",
+        },
+        policy: {
+          installation: "AVAILABLE",
+          authentication: "ON_INSTALL",
+        },
+        category: "Productivity",
+      },
+    ],
+  };
+}
+
+async function buildStagingTree(parent, pluginSource) {
+  const staging = await mkdtemp(join(parent, ".opensocrates.staging-"));
+  try {
+    const marketplace = join(staging, MARKETPLACE_RELATIVE);
+    const plugin = join(staging, PLUGIN_RELATIVE);
+    await mkdir(dirname(marketplace), { recursive: true, mode: 0o700 });
+    await mkdir(dirname(plugin), { recursive: true, mode: 0o700 });
+    await cp(pluginSource, plugin, { recursive: true, preserveTimestamps: true });
+    await writeFile(marketplace, `${JSON.stringify(expectedMarketplace(), null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await writeFile(join(staging, MARKER_NAME), `${JSON.stringify(MARKER, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await verifyExtractedPackage(plugin);
+    return staging;
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+function entryRoot(entry) {
+  if (entry === null) {
+    return null;
+  }
+  if (typeof entry.root !== "string" || entry.root.trim().length === 0) {
+    fail(`Codex marketplace ${MARKETPLACE_NAME} has no usable root`);
+  }
+  return resolve(entry.root);
+}
+
+function removeRegistration(entry, state) {
+  if (state.kind === "installed") {
+    runCodexJson(["plugin", "remove", PLUGIN_ID, "--json"]);
+  }
+  if (entry !== null) {
+    runCodexJson(["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--json"]);
+  }
+}
+
+function addRegistration(root, installPlugin) {
+  runCodexJson(["plugin", "marketplace", "add", root, "--json"]);
+  if (installPlugin) {
+    return runCodexJson(["plugin", "add", PLUGIN_ID, "--json"]);
+  }
+  return null;
+}
+
+function removeRegistrationBestEffort() {
+  const entry = (() => {
+    try {
+      return marketplaceEntry();
+    } catch {
+      return null;
+    }
+  })();
+  if (entry === null) {
+    return;
+  }
+  try {
+    const state = pluginState();
+    if (state.kind === "installed") {
+      run(codexBinary(), ["plugin", "remove", PLUGIN_ID, "--json"], { allowFailure: true });
+    }
+  } catch {
+    // Rollback continues with marketplace cleanup.
+  }
+  run(codexBinary(), ["plugin", "marketplace", "remove", MARKETPLACE_NAME, "--json"], {
+    allowFailure: true,
+  });
+}
+
+async function installVerifiedPackage(pluginSource, action) {
+  requireCodex();
+  const paths = managedPaths();
+  await mkdir(paths.parent, { recursive: true, mode: 0o700 });
+
+  const previousEntry = marketplaceEntry();
+  if (previousEntry !== null && entryRoot(previousEntry) !== paths.root) {
+    fail(
+      `marketplace ${MARKETPLACE_NAME} is already registered at ${entryRoot(previousEntry)}; ` +
+        "refusing to overwrite an unmanaged location",
+    );
+  }
+  const previousState = previousEntry === null ? { kind: "missing", version: null } : pluginState();
+  if (await exists(paths.root)) {
+    await requireOwnedRoot(paths.root);
+  }
+
+  const staging = await buildStagingTree(paths.parent, pluginSource);
+  const backup = join(paths.parent, `.opensocrates.backup-${randomUUID()}`);
+  let registrationRemoved = false;
+  let backupCreated = false;
+  let newRootActive = false;
+  try {
+    if (previousEntry !== null) {
+      registrationRemoved = true;
+      removeRegistration(previousEntry, previousState);
+    }
+    if (await exists(paths.root)) {
+      await rename(paths.root, backup);
+      backupCreated = true;
+    }
+    await rename(staging, paths.root);
+    newRootActive = true;
+    const result = addRegistration(paths.root, true);
+    const state = pluginState();
+    if (
+      result?.pluginId !== PLUGIN_ID ||
+      result?.version !== PRODUCT_VERSION ||
+      state.kind !== "installed" ||
+      state.version !== PRODUCT_VERSION
+    ) {
+      fail("Codex did not confirm the expected installed plugin and version");
+    }
+    if (backupCreated) {
+      await requireOwnedRoot(backup);
+      await rm(backup, { recursive: true });
+    }
+    const verb = action === "update" ? "updated" : "installed";
+    console.log(`OpenSocrates ${PRODUCT_VERSION} ${verb} successfully.`);
+    console.log(`Managed marketplace: ${paths.root}`);
+    console.log("Start a new Codex task to load the updated skills and hooks.");
+  } catch (error) {
+    removeRegistrationBestEffort();
+    if (newRootActive && (await exists(paths.root))) {
+      await requireOwnedRoot(paths.root);
+      await rm(paths.root, { recursive: true });
+    }
+    if (backupCreated && (await exists(backup))) {
+      await requireOwnedRoot(backup);
+      await rename(backup, paths.root);
+    }
+    if (registrationRemoved && previousEntry !== null) {
+      try {
+        addRegistration(paths.root, previousState.kind === "installed");
+      } catch (rollbackError) {
+        fail(`${error.message}; rollback also failed: ${rollbackError.message}`);
+      }
+    }
+    throw error;
+  } finally {
+    if (await exists(staging)) {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+}
+
+async function showStatus() {
+  requireCodex();
+  const paths = managedPaths();
+  const entry = marketplaceEntry();
+  if (entry === null) {
+    if (await exists(paths.root)) {
+      await requireOwnedRoot(paths.root);
+      console.log(`OpenSocrates files are present but not registered: ${paths.root}`);
+    } else {
+      console.log("OpenSocrates is not installed.");
+    }
+    return;
+  }
+  if (entryRoot(entry) !== paths.root) {
+    fail(`OpenSocrates is registered at an unmanaged location: ${entryRoot(entry)}`);
+  }
+  await requireOwnedRoot(paths.root);
+  const state = pluginState();
+  if (state.kind === "installed") {
+    console.log(`OpenSocrates ${state.version ?? "unknown"} is installed.`);
+  } else if (state.kind === "available") {
+    console.log(`OpenSocrates ${state.version ?? "unknown"} is available but not installed.`);
+  } else {
+    console.log("The OpenSocrates marketplace is registered, but the plugin is missing.");
+  }
+}
+
+async function removeInstalled() {
+  requireCodex();
+  const paths = managedPaths();
+  const entry = marketplaceEntry();
+  if (entry !== null && entryRoot(entry) !== paths.root) {
+    fail(`OpenSocrates is registered at an unmanaged location: ${entryRoot(entry)}`);
+  }
+  const state = entry === null ? { kind: "missing", version: null } : pluginState();
+  removeRegistration(entry, state);
+  if (await exists(paths.root)) {
+    await requireOwnedRoot(paths.root);
+    await rm(paths.root, { recursive: true });
+  }
+  console.log("OpenSocrates was removed from Codex.");
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const options = parseCli(argv);
+  if (options.action === "help") {
+    showHelp();
+    return 0;
+  }
+  if (options.action === "status") {
+    await showStatus();
+    return 0;
+  }
+  if (options.action === "remove") {
+    await removeInstalled();
+    return 0;
+  }
+  if (
+    ["install", "update"].includes(options.action) &&
+    (process.platform !== "darwin" || process.arch !== "arm64")
+  ) {
+    fail(
+      `OpenSocrates ${PRODUCT_VERSION} prebuilt installation supports darwin-arm64 only; ` +
+        `detected ${process.platform}-${process.arch}`,
+    );
+  }
+
+  const prepared = await prepareVerifiedPackage(options);
+  try {
+    console.log(
+      `Verified OpenSocrates ${PRODUCT_VERSION} release and ${prepared.checkedFiles} package files.`,
+    );
+    if (options.action === "verify") {
+      return 0;
+    }
+    await installVerifiedPackage(prepared.pluginRoot, options.action);
+    return 0;
+  } finally {
+    await rm(prepared.scratch, { recursive: true, force: true });
+  }
+}
+
+let invokedDirectly = false;
+if (process.argv[1] !== undefined) {
+  try {
+    invokedDirectly = realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    invokedDirectly = false;
+  }
+}
+if (invokedDirectly) {
+  main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`error: ${message}`);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opensocrates",
+  "version": "1.0.0",
+  "description": "Install and manage the OpenSocrates reasoning framework for Codex.",
+  "type": "module",
+  "bin": {
+    "opensocrates": "installer/opensocrates.mjs"
+  },
+  "files": [
+    "installer/opensocrates.mjs",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "VERSION"
+  ],
+  "scripts": {
+    "test": "node --test installer/opensocrates.test.mjs && npm run test:npx",
+    "test:npx": "node installer/package-smoke.mjs",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ParkerHwang/OpenSocrates.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ParkerHwang/OpenSocrates/issues"
+  },
+  "homepage": "https://github.com/ParkerHwang/OpenSocrates#readme",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "ai",
+    "codex",
+    "reasoning",
+    "agent",
+    "installer",
+    "critical-thinking",
+    "socratic"
+  ]
+}