--- name: mastery-path description: Launch or recover the Mastery Path web interface for the current standalone local workspace. Use when the user invokes $mastery-path by itself, asks to open or resume Mastery Path, needs to repair its local connector, or supplies a Mastery Path bootstrap request. The skill initializes an unconfigured workspace through its bundled bootstrap reference, or starts and reconnects the existing origin-restricted local Codex App Server bridge while keeping Codex credentials and canonical transcripts local. --- # Mastery Path Package version: **0.5.4** Treat bare `$mastery-path` as the application launcher. Do not require the user to remember `init`, `start`, `resume`, or `connect` commands. `$mastery-path connect` is a compatibility alias for this same workflow. Mastery Path is a web view and command surface for the user's real local Codex workspace. Local Codex owns authentication, task identity, transcript history, model work, tools, files, sandboxing, and approvals. Never send Codex credentials, local paths, raw App Server events, or transcript storage to the website. ## Choose the launch path Resolve the exact physical directory with `pwd -P`. Inspect only these expected workspace surfaces before deciding what to do: - `.masterypath/workspace.json` - `.masterypath/connector.json` - `.masterypath/runtime/0.5.4/runtime.json` - `.masterypath/runtime/0.5.4/scripts/connect.mjs` - `.masterypath/runtime/0.5.4/scripts/studio-store.mjs` - `.masterypath/runtime/0.5.4/runtime/contracts.mjs` - `.masterypath/runtime/0.5.4/runtime/workspace.mjs` - `.masterypath/runtime/0.5.4/runtime/store/db.mjs` - `.masterypath/runtime/0.5.4/references/studio-handoff/SKILL.md` - `.agents/skills/mastery-path/SKILL.md` - `.agents/skills/mastery-path/references/bootstrap.md` - `.agents/skills/mastery-path/scripts/launch.mjs` Classify the workspace and state the result plainly: - **New:** no valid `.masterypath/workspace.json` exists. Read [references/bootstrap.md](references/bootstrap.md) completely and run its guided bootstrap. Do not silently turn an unrelated existing project into a Mastery Path workspace. - **Ready but stopped:** the manifest and package are valid, no matching live connector record exists, and the configured port is free. Run the small installed launcher, which validates and imports the exact pinned runtime. - **Running:** `.masterypath/connector.json` matches the workspace ID, origin, and port; its PID is live; and the process command is this workspace's exact installed launcher with the recorded arguments. Open the recorded site. If the browser no longer has its private capability, offer a controlled restart; never kill the process without approval. The task that invokes this launch is the current launcher/control task. Keep its transcript in native Codex and do not expose it as an ordinary web conversation. - **Stale or conflicting:** the configured port belongs to another process, workspace, or site, or the runtime record no longer describes its live PID. Report the conflict and stop. Do not reuse, terminate, delete, or replace it without approval. - **Damaged:** the manifest is malformed or required package files are missing or changed unexpectedly. Read the repair section of the bootstrap reference, show the proposed changes, and obtain approval before writing. Do not scan sibling repositories, the home directory, Documents, or Downloads for another workspace. Do not create, rename, select, or resume a product conversation during launch. ## Validate initialized state Require `.masterypath/workspace.json` to be a small JSON object with: - `schemaVersion: 1` - a nonempty opaque `workspaceId` - `workspaceName` matching the current root folder name - an exact `siteOrigin` using HTTPS, except development at `http://127.0.0.1:`; reject `localhost` and other HTTP hosts - an integer `connectorPort` from 1024 through 65535 - optional `launcherThreadId` containing only the replaceable native task ID used to launch and troubleshoot the connector - `runtimeVersion: "0.5.4"` - `runtimeManifestSha256` containing the lowercase SHA-256 of the exact installed `runtime.json` bytes - a valid ISO-8601 `createdAt` Reject unknown credentials, browser capabilities, transcript copies, or an absolute workspace path in the manifest. Small JSON metadata does not select JSON as the permanent storage model for later Mastery Path artifacts. When present, require `.masterypath/connector.json` to contain only `schemaVersion`, the matching `workspaceId`, the connector PID, matching site origin and port, and `startedAt`. It is ephemeral launcher state, not a saved browser capability. Never accept a token, transcript, command, or absolute path there. The connector creates it only after App Server starts and removes it on clean shutdown. Validate the package before launch: 1. Require `.masterypath/runtime/0.5.4/runtime.json` to be a regular, nonsymlinked file containing exactly this shape: ```json { "version": "0.5.4", "integrity": "sha256", "assets": { "connect.mjs": { "path": "scripts/connect.mjs", "sha256": "" }, "studio-store.mjs": { "path": "scripts/studio-store.mjs", "sha256": "" }, "runtime-contracts.mjs": { "path": "runtime/contracts.mjs", "sha256": "" }, "runtime-workspace.mjs": { "path": "runtime/workspace.mjs", "sha256": "" }, "runtime-store-db.mjs": { "path": "runtime/store/db.mjs", "sha256": "" }, "studio-handoff.md": { "path": "references/studio-handoff/SKILL.md", "sha256": "" } } } ``` Reject unknown fields, absolute paths, traversal, symlinks, asset-name or path changes, non-lowercase 64-character hashes, and any version or integrity value other than the exact values above. 2. Resolve each descriptor path strictly below `.masterypath/runtime/0.5.4/`, require each target to be a regular, nonsymlinked file, and require its SHA-256 to equal the descriptor before reading or executing it. A mismatch is damaged state; never update the descriptor to bless changed bytes. 3. Read the verified connector, Studio store, runtime contracts, workspace, and store-database modules. Confirm the verified handoff skill declares `name: mastery-path-studio-handoff`. 4. Run `node --check` on all five verified `.mjs` files and confirm the current Node runtime provides `node:sqlite`. Do not install a database package as a bootstrap fallback. 5. Confirm the connector binds only `127.0.0.1`, restricts the exact website origin, requires a random per-run browser capability, exposes a fixed operation allowlist, and starts Codex App Server as a child over stdio. 6. Show the workspace name, exact site origin, runtime version, and verified runtime paths before starting anything. ## Launch Use the manifest's exact origin, port, and physical workspace root. When `CODEX_THREAD_ID` is available, pass it as the canonical launcher task: ```text node .agents/skills/mastery-path/scripts/launch.mjs --site --port --project --launcher-thread "$CODEX_THREAD_ID" ``` The launcher revalidates the pinned descriptor, exact runtime inventory, symlink boundaries, and every asset hash before it imports the connector. Do not bypass it by running the hidden connector directly. Run it in one long-lived local terminal session. Wait for `Mastery Path local Codex connector is ready.` The connector prints one `Open:` URL containing a short-lived capability in the fragment. With the user's browser or Computer Use approval, open that private URL in the intended browser profile. Never paste or echo the full URL into a task, documentation, log, or another site. The first connection may trigger the browser's local-network permission; explain that Mastery Path is asking to talk only to its connector on this device. Keep the terminal session running while the website is connected. Stopping it closes the connection. Do not install a daemon, expose the listener beyond the local machine, or launch a second connector. ## Task and transcript behavior The task that invokes bare `$mastery-path` is the launcher/control task for that connector run. The connector records its canonical ID when Codex exposes `CODEX_THREAD_ID`, replaces any stale launcher reference, and keeps that task out of the normal web thread list. The web connection-health surface may open it in native Codex for troubleshooting, but it must never mirror its transcript. After launch, the dashboard presents the remaining real project threads without creating or selecting one. The visitor chooses an existing conversation or creates a new native Codex thread from the web. A fresh connector launch returns to this neutral chooser; an ordinary refresh in the same connector session may restore the browser's current selection and unsent draft. Other sidebar entries must be real Codex tasks whose working directory matches this workspace. Web-created conversations must create real local Codex tasks. Completed App Server items and native Codex history remain authoritative. Never create a web-only transcript or duplicate task because desktop indexing is delayed. Allow only one model turn at a time in a task. Reconcile after completion, restart, or disconnect. Do not race native Codex and the web as hidden concurrent writers. ## Truthful failures Stop and report the precise condition when the manifest, package, site origin, port ownership, App Server initialization, browser permission, capability, task identity, or active-turn state cannot be verified. Never substitute canned messages, the historical folder mailbox, a per-request deep link, or another manual Codex Send for a failed real connection.