[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7F0FSCAYJ90P78F6BEQSVAA":3,"skill-same:01M7F0FSCAYJ90P78F6BEQSVAA":50},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7F0FSCAYJ90P78F6BEQSVAA","dev-instance",null,"Run the current worktree as a production-shaped local dev instance with web, Slack, or both, on a real LLM + Postgres. Each developer uses their own set of Slack apps from their own machine's pool store, so many worktrees (yours and a teammate's) can run reachable at once without colliding. Use when asked to \u002Fdev-instance, \"spin this up so I can QA it in Slack\", or \"let me test your branch end to end\".","irisfeng\u002Fmoqi","irisfeng","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6022447?v=4","01M7F0EZD855PPJ4X8Q6G9EFS5","01M7F0EZDS1M2D36FZ71RD1XTP",1,"MIT","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fdev-instance\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: dev-instance\ndescription: Run the current worktree as a production-shaped local dev instance with web, Slack, or both, on a real LLM + Postgres. Each developer uses their own set of Slack apps from their own machine's pool store, so many worktrees (yours and a teammate's) can run reachable at once without colliding. Use when asked to \u002Fdev-instance, \"spin this up so I can QA it in Slack\", or \"let me test your branch end to end\".\n---\n\n# dev-instance\n\n`dev-instance` runs the current worktree with the surfaces needed for the task.\nChoose web for browser\u002Fadmin work, Slack for bot work, and both only for cross-surface QA. It is the way to QA a\nbranch end to end: real LLM turns, a real sandbox, a real local Postgres (empty by\ndefault; opt in to prod data), and the real Slack\u002Fweb\u002Fadmin surfaces.\n\nUse the repo-root launcher (a thin wrapper over the TypeScript CLI in `scripts\u002Fdev\u002F`;\nevery command accepts `--json` for machine-readable output):\n\n```bash\nbash scripts\u002Fdev-instance.sh up --surface web\nbash scripts\u002Fdev-instance.sh up --surface slack\nbash scripts\u002Fdev-instance.sh up --surface both\nbash scripts\u002Fdev-instance.sh status\nbash scripts\u002Fdev-instance.sh down\nbash scripts\u002Fdev-instance.sh doctor\nbash scripts\u002Fdev-instance.sh canary\nbash scripts\u002Fdev-instance.sh restart [child]\nbash scripts\u002Fdev-instance.sh logs [child] [-f]\n```\n\n`npm run dev-instance`, `npm run dev-instance:status`, `npm run dev-instance:down`, and\n`npm run dev-instance:doctor` are equivalent. The Codex-visible skill copy lives at\n`.codex\u002Fskills\u002Fdev-instance\u002FSKILL.md`; keep the two skill descriptions equivalent.\n\nNew instances default to web only. `npm run dev-instance:web`,\n`npm run dev-instance:slack`, and `npm run dev-instance:both` select a surface explicitly.\nBare `up` preserves the mode of an existing instance. Explicitly selecting a different\nsurface tears down and boots the worktree again, claiming the appropriate slot.\n`--no-slack` (and `DEV_INSTANCE_NO_SLACK=1`) remain aliases for web only.\n\n## What `up` Starts\n\n`up --surface slack` and `up --surface both` claim one free Slack app slot from **this machine's** pool store (see \"Slack reach\"\nbelow), then spawns a **per-slot supervisor daemon** that owns the production-shaped stack:\n\n- core API + workers in every mode\n- Slack Socket Mode plugin in `slack` and `both`\n- web UI, admin, and portal front door in `web` and `both`\n\nWeb-only instances need no Slack app or pool credentials. Slack-only instances skip\nweb dependencies, builds, and web\u002Fportal processes.\n\nPort slots expand automatically beyond 16, up to the TCP port range (8,207 slots at\nthe default base port of 8080); machine resources will usually limit capacity first.\nSlots 1–16 retain their existing ports. Allocation skips occupied port blocks.\nStartup refuses occupied ports without terminating their listeners; if a port is\ntaken after allocation, stop the failed instance and retry `up` to select a free block.\n\nThe supervisor restarts crashed children with backoff, refuses occupied ports,\nhealth-probes everything every 10s, and writes a\nheartbeat so slot reclaim can tell \"actively in use\" from \"abandoned\".\n\n**When Slack is enabled, `up` only prints success after proving the bot is reachable**: the Slack socket must be\nthe app's _only_ connection (`num_connections == 1`, read from the hello frame) and — when\nthe slot has a `CANARY_CHANNEL` — a posted canary message must arrive back over that same\nsocket. If Slack reports multiple connections, `up` flags the slot for 30 minutes and\nauto-rotates to the next one. The count is a snapshot from the last hello frame, not\na continuously refreshed inventory. Its `debug_info.host` identifies Slack's server,\nnot another client's machine; it cannot locate a competing instance. A canary that\nnever returns leaves delivery unverified; `up` flags and rotates past that too.\n\n**Re-running `up` on a live instance is a reload, not a no-op**: it re-reads your shell\nenv, dev.env, and `.env`, diffs against what the children are running, and does a rolling\nrestart + re-verification when anything changed (`--force` to restart regardless,\n`--rotate` to move to a different Slack app).\n\nOpen the portal URL printed by the CLI. Direct web\u002Fadmin URLs are also printed for\ndebugging, but the portal URL is the prod-like path.\n\n## Sandbox: local Docker by default\n\nThe agent's `execute` sandbox runs as a **local Docker container** (`SANDBOX_BACKEND=local`)\nwhen the worktree's code supports it — no cloud credential, no tunnel, no microVM cold\nstarts, and the sandbox reaches core's self-API at `host.docker.internal` directly. Build\nthe image once per machine with `npm run sandbox:local:build` (the CLI warns if it's\nmissing or stale). Use local Docker unless you are specifically testing the cloud path.\n\nFor prod-parity QA, pass `--sandbox \u003Cbackend>` to run against your deployment's real\nsandbox provider instead. That path validates the provider credential and opens a tunnel\nso the remote sandbox can call back to your local core, so it needs whatever that provider\nrequires; the local backend needs nothing but Docker.\n\n## Slack reach: your apps vs a teammate's\n\nThis is the part people get wrong, so it's worth stating plainly.\n\nA Slack app's **Socket Mode** connection is single-owner: if two running instances point\nat the _same_ app, Slack load-balances inbound messages between them and each instance\nsilently loses half. So the rule is **one live instance per Slack app**.\n\nThe way we keep out of each other's way is simple: **every developer has their own set of\nSlack apps**, listed as `poolN.env` files in their **own machine's** pool store\n(`~\u002F.config\u002Fqm\u002Fslack-pool`). `up` claims the first free slot on _this_ machine and boots\nthat app's bot; the script prints its `@handle`. You QA by DMing that bot in\n`example.slack.com`.\n\n- **Your machine** (Alice's): the pool holds `pool1.env … pool10.env`, which are the apps\n  `bot1 … bot10`. So up to 10 worktrees can run reachable at once here; each `up` grabs\n  the next free slot, `down` frees it. DM whichever `@botN` the script printed.\n- **A teammate's machine** (e.g. Carol's): a _different_ set of apps in _their_ local pool\n  store. Their instances claim their apps; yours claim yours. You never collide, because you\n  are never pointing at the same app — and there is no shared registry, no `#worktree`\n  prefix, and no relay to coordinate. Each of you just DMs your own bot.\n\nThe per-machine pool lease (an atomic lock per slot) also stops two worktrees on the _same_\nmachine from grabbing the same slot. Before connecting, `up` sweeps the machine for\norphaned processes still holding the slot's Slack app token (e.g. a plugin another\nworktree's teardown missed) and kills them. If every slot is taken, `up` reclaims one —\nbut **never a slot whose supervisor heartbeat is fresh**: an actively used instance can't\nbe stolen mid-QA; only dead\u002Flegacy leases fall back to the old not-today \u002F 4-hour rule.\n\nTo add capacity, mint more Slack apps from `src\u002Fslack\u002Fmanifest.json` (one Socket Mode\napp each, with `connections:write` for the app-level token) and drop a `poolN.env`\ncontaining `SLACK_BOT_TOKEN` (`xoxb-`), `SLACK_APP_TOKEN` (`xapp-`), and `HANDLE` into your\npool store. The boot canary picks its channel automatically: a channel named `dev-canary`\nif the bot is in one, else a `ci-*` throwaway it is in — never a human channel — and the\ncanary message is deleted right after it round-trips. `CANARY_CHANNEL=\u003Cchannel id>` in the\nslot env overrides. With no eligible channel at all, `up` prints `delivery unverified` (or\nfails under `--strict`).\n\nIf its worktree disappears, the supervisor shuts down its children and releases its\nlease on the next heartbeat (within 15 seconds, plus shutdown time). Always run `down`\nbefore intentionally removing a worktree.\n\nA forgotten instance cleans itself up: after 24 hours with no handled Slack turns,\ninteractions, reloads, or restarts, the supervisor tears itself down and frees the slot\non its next idle check (every 10 minutes). Ambient workspace events, health checks,\nstatus reads, and canaries (including `dev doctor`) do not reset the timer. This is\nan idle timeout, not a fixed 24-hour lifetime. It only retires instances running this\nsupervisor; extra connections on another host must be stopped on that host. `DEV_INSTANCE_IDLE_HOURS` overrides the timeout; `0` disables it.\n\n## Real by Default\n\nThe dev instance should exercise the real system:\n\n- real LLM: needs a model credential for the harness you run. Core supports\n  `HARNESS=pi|claude`; the launcher runs Pi when it finds an Anthropic key and honours an\n  explicit `HARNESS=claude`. Pass `DEV_INSTANCE_ALLOW_MOCK=1` for a deliberate no-model\n  wiring check. Pi's GPT models can also use a ChatGPT subscription: set `CODEX_AUTH_FILE`\n  to a local Codex CLI `auth.json`. The auth-file path is for local dev instances; deployed\n  production processes use an API key or a keychain credential (`CODEX_AUTH_CREDENTIAL` \u002F\n  `CLAUDE_AUTH_CREDENTIAL`), whose secret lives encrypted in its owner's keychain.\n- real durability: uses `DATABASE_URL` when supplied; otherwise starts\u002Freuses a local\n  Docker Postgres container and runs core with `SESSION_STORE=postgres` and\n  `RUN_STORE=postgres`\n- production data is never copied into a dev instance\n- captured model context: request capture is on unless overridden, so you can read back what the model was actually sent\n- fast local edits: runs Node surfaces with `--watch` and serves the web UI through\n  Vite HMR on the dev surface instead of a separate browser build loop\n- stale pool recovery: `status` shows each deploy's start time and age; if all pool\n  apps are taken, `up` reclaims a slot not started today or older than 4 hours\n- local admin seed: for a self-provisioned local DB, empty `admin_grants` are seeded\n  from `DEV_INSTANCE_ADMIN_PRINCIPAL` or the local OS user; explicit `ADMIN_GRANTS`\n  still wins\n- local portal auth: the launcher sets a localhost-only portal auth bypass, signing in\n  as `DEV_INSTANCE_ADMIN_PRINCIPAL`, the first `ADMIN_GRANTS` principal, the first\n  durable `org_admin` in Postgres, or the local OS user. Production portal auth remains\n  real OIDC.\n\nOnly use escape hatches for deliberate wiring checks — this is how you ask for _less_ than\nthe full real stack when a test doesn't need it:\n\n```bash\nDEV_INSTANCE_ALLOW_MOCK=1 bash scripts\u002Fdev-instance.sh up\nDEV_INSTANCE_ALLOW_MEMORY=1 bash scripts\u002Fdev-instance.sh up\nDEV_INSTANCE_WATCH=0 bash scripts\u002Fdev-instance.sh up\nDEV_INSTANCE_RECLAIM_STALE=0 bash scripts\u002Fdev-instance.sh up\n```\n\n## Env Discovery\n\nThe launcher reads values from, in priority order: exported shell env, the machine-global\n`~\u002F.config\u002Fqm\u002Fdev.env`, your login shell (for a model credential exported there), and this\nworktree's `.env` (seeded from the main checkout in linked worktrees). Slack pool tokens\ndefault to `~\u002F.config\u002Fqm\u002Fslack-pool`.\n\nWhen a cloud sandbox backend is configured it also validates that provider's access at\nstartup, refreshes a stale provider token from the provider CLI's own logged-in session\nwhere it can, and — if a tunnel binary is present — opens a quick tunnel so sandbox\nself-API calls can reach your local core. None of that runs on the default local backend.\n\n## After Startup\n\nReport the slot, enabled surfaces, their URLs or Slack handle, and log directory. To test Slack-specific\nbehavior, DM the printed `@\u003Chandle>` (on Alice's machine that's one of `@bot1 … @bot10`)\nin `example.slack.com`; for admin and web behavior, open the printed portal URL. Keep\nreview instances running until the PR merges. After merge, run\n`bash scripts\u002Fdev-instance.sh down` from that worktree with the same pool-store override\nused for `up`, before removing the worktree. Verify the instance's supervisor and children\nhave exited and its lease is released. Keep shared Postgres and persistent data intact.\nIf the user asks to keep the instance beyond merge, retain its worktree too. For work\nwithout a PR, tear down when QA is finished unless the user requested a running demo.\n\n## Troubleshooting\n\n**Start with `dev doctor` (or `doctor --json`).** It runs the checks that used to take a\ndebugging session by hand — socket exclusivity (`num_connections`), a live canary\nround trip, env\u002Fgit drift since boot, per-child health and restart counts, stale leases,\nport squatters, machine-wide token orphans, Docker daemon — and prints a ranked diagnosis\nwith a remedy per finding. `doctor --fix` applies the safe ones (child restarts).\n\n**Bot never replies to a DM (silent bot).** The new `up` catches the two big causes at\nboot: multiple reported connections to the same app (flags the slot and auto-rotates)\nand a Slack app whose events never arrive (canary fails → flags the slot and rotates).\nCheck local processes and other deployments before attributing a connection count to\na live competitor. After cleanup, reconnect to obtain a fresh hello count; rereading\nhealth alone returns the previous snapshot. The 10s health probe logs\n`DEGRADED: num_connections=N` in `supervisor.log` when it observes a count transition\nabove one, but cannot detect a new competitor while the hello snapshot is unchanged.\nPeriodic canaries can detect delivery loss; `dev canary` tests delivery on demand.\nA successful canary does not establish exclusivity. `dev up --rotate` moves to a fresh slot.\n\nFor a slot flagged `canary-failed`, check networking, event subscriptions, permissions,\nand competing connections first. If the app configuration needs rebuilding, use\napi.slack.com **signed into the example workspace** (the dev console is\nper-workspace-identity — use \"Sign in to another workspace\" if it lists the wrong one):\nCreate New App → From a manifest → paste `src\u002Fslack\u002Fmanifest.json` (give it a unique\n`name` and bot `display_name`; old handles stay taken) → Install to Workspace → Basic\nInformation → App-Level Tokens → Generate with the `connections:write` scope. Write the Bot\ntoken (`xoxb-…`) and app-level token (`xapp-…`) into `poolN.env`, delete `poolN.flag.json`,\nthen run `up` again to verify the replacement. Reinstalling an existing app may also\nresolve configuration drift; verify delivery afterward.\n\nTwo smaller gotchas: a freshly-created bot isn't in Slack's \"New message\" people search for a\nminute or two — open its DM deterministically via `conversations.open` (bot token + your user\nid) and navigate to `app.slack.com\u002Fclient\u002F\u003Cteam-id>\u002F\u003CD-channel-id>`. And the browser's Slack\nlogin drops easily during long automated sessions; re-authenticating is a Google SSO you have\nto complete yourself.\n","# dev-instance\n\n`dev-instance` runs the current worktree with the surfaces needed for the task.\nChoose web for browser\u002Fadmin work, Slack for bot work, and both only for cross-surface QA. It is the way to QA a\nbranch end to end: real LLM turns, a real sandbox, a real local Postgres (empty by\ndefault; opt in to prod data), and the real Slack\u002Fweb\u002Fadmin surfaces.\n\nUse the repo-root launcher (a thin wrapper over the TypeScript CLI in `scripts\u002Fdev\u002F`;\nevery command accepts `--json` for machine-readable output):\n\n```bash\nbash scripts\u002Fdev-instance.sh up --surface web\nbash scripts\u002Fdev-instance.sh up --surface slack\nbash scripts\u002Fdev-instance.sh up --surface both\nbash scripts\u002Fdev-instance.sh status\nbash scripts\u002Fdev-instance.sh down\nbash scripts\u002Fdev-instance.sh doctor\nbash scripts\u002Fdev-instance.sh canary\nbash scripts\u002Fdev-instance.sh restart [child]\nbash scripts\u002Fdev-instance.sh logs [child] [-f]\n```\n\n`npm run dev-instance`, `npm run dev-instance:status`, `npm run dev-instance:down`, and\n`npm run dev-instance:doctor` are equivalent. The Codex-visible skill copy lives at\n`.codex\u002Fskills\u002Fdev-instance\u002FSKILL.md`; keep the two skill descriptions equivalent.\n\nNew instances default to web only. `npm run dev-instance:web`,\n`npm run dev-instance:slack`, and `npm run dev-instance:both` select a surface explicitly.\nBare `up` preserves the mode of an existing instance. Explicitly selecting a different\nsurface tears down and boots the worktree again, claiming the appropriate slot.\n`--no-slack` (and `DEV_INSTANCE_NO_SLACK=1`) remain aliases for web only.\n\n## What `up` Starts\n\n`up --surface slack` and `up --surface both` claim one free Slack app slot from **this machine's** pool store (see \"Slack reach\"\nbelow), then spawns a **per-slot supervisor daemon** that owns the production-shaped stack:\n\n- core API + workers in every mode\n- Slack Socket Mode plugin in `slack` and `both`\n- web UI, admin, and portal front door in `web` and `both`\n\nWeb-only instances need no Slack app or pool credentials. Slack-only instances skip\nweb dependencies, builds, and web\u002Fportal processes.\n\nPort slots expand automatically beyond 16, up to the TCP port range (8,207 slots at\nthe default base port of 8080); machine resources will usually limit capacity first.\nSlots 1–16 retain their existing ports. Allocation skips occupied port blocks.\nStartup refuses occupied ports without terminating their listeners; if a port is\ntaken after allocation, stop the failed instance and retry `up` to select a free block.\n\nThe supervisor restarts crashed children with backoff, refuses occupied ports,\nhealth-probes everything every 10s, and writes a\nheartbeat so slot reclaim can tell \"actively in use\" from \"abandoned\".\n\n**When Slack is enabled, `up` only prints success after proving the bot is reachable**: the Slack socket must be\nthe app's _only_ connection (`num_connections == 1`, read from the hello frame) and — when\nthe slot has a `CANARY_CHANNEL` — a posted canary message must arrive back over that same\nsocket. If Slack reports multiple connections, `up` flags the slot for 30 minutes and\nauto-rotates to the next one. The count is a snapshot from the last hello frame, not\na continuously refreshed inventory. Its `debug_info.host` identifies Slack's server,\nnot another client's machine; it cannot locate a competing instance. A canary that\nnever returns leaves delivery unverified; `up` flags and rotates past that too.\n\n**Re-running `up` on a live instance is a reload, not a no-op**: it re-reads your shell\nenv, dev.env, and `.env`, diffs against what the children are running, and does a rolling\nrestart + re-verification when anything changed (`--force` to restart regardless,\n`--rotate` to move to a different Slack app).\n\nOpen the portal URL printed by the CLI. Direct web\u002Fadmin URLs are also printed for\ndebugging, but the portal URL is the prod-like path.\n\n## Sandbox: local Docker by default\n\nThe agent's `execute` sandbox runs as a **local Docker container** (`SANDBOX_BACKEND=local`)\nwhen the worktree's code supports it — no cloud credential, no tunnel, no microVM cold\nstarts, and the sandbox reaches core's self-API at `host.docker.internal` directly. Build\nthe image once per machine with `npm run sandbox:local:build` (the CLI warns if it's\nmissing or stale). Use local Docker unless you are specifically testing the cloud path.\n\nFor prod-parity QA, pass `--sandbox \u003Cbackend>` to run against your deployment's real\nsandbox provider instead. That path validates the provider credential and opens a tunnel\nso the remote sandbox can call back to your local core, so it needs whatever that provider\nrequires; the local backend needs nothing but Docker.\n\n## Slack reach: your apps vs a teammate's\n\nThis is the part people get wrong, so it's worth stating plainly.\n\nA Slack app's **Socket Mode** connection is single-owner: if two running instances point\nat the _same_ app, Slack load-balances inbound messages between them and each instance\nsilently loses half. So the rule is **one live instance per Slack app**.\n\nThe way we keep out of each other's way is simple: **every developer has their own set of\nSlack apps**, listed as `poolN.env` files in their **own machine's** pool store\n(`~\u002F.config\u002Fqm\u002Fslack-pool`). `up` claims the first free slot on _this_ machine and boots\nthat app's bot; the script prints its `@handle`. You QA by DMing that bot in\n`example.slack.com`.\n\n- **Your machine** (Alice's): the pool holds `pool1.env … pool10.env`, which are the apps\n  `bot1 … bot10`. So up to 10 worktrees can run reachable at once here; each `up` grabs\n  the next free slot, `down` frees it. DM whichever `@botN` the script printed.\n- **A teammate's machine** (e.g. Carol's): a _different_ set of apps in _their_ local pool\n  store. Their instances claim their apps; yours claim yours. You never collide, because you\n  are never pointing at the same app — and there is no shared registry, no `#worktree`\n  prefix, and no relay to coordinate. Each of you just DMs your own bot.\n\nThe per-machine pool lease (an atomic lock per slot) also stops two worktrees on the _same_\nmachine from grabbing the same slot. Before connecting, `up` sweeps the machine for\norphaned processes still holding the slot's Slack app token (e.g. a plugin another\nworktree's teardown missed) and kills them. If every slot is taken, `up` reclaims one —\nbut **never a slot whose supervisor heartbeat is fresh**: an actively used instance can't\nbe stolen mid-QA; only dead\u002Flegacy leases fall back to the old not-today \u002F 4-hour rule.\n\nTo add capacity, mint more Slack apps from `src\u002Fslack\u002Fmanifest.json` (one Socket Mode\napp each, with `connections:write` for the app-level token) and drop a `poolN.env`\ncontaining `SLACK_BOT_TOKEN` (`xoxb-`), `SLACK_APP_TOKEN` (`xapp-`), and `HANDLE` into your\npool store. The boot canary picks its channel automatically: a channel named `dev-canary`\nif the bot is in one, else a `ci-*` throwaway it is in — never a human channel — and the\ncanary message is deleted right after it round-trips. `CANARY_CHANNEL=\u003Cchannel id>` in the\nslot env overrides. With no eligible channel at all, `up` prints `delivery unverified` (or\nfails under `--strict`).\n\nIf its worktree disappears, the supervisor shuts down its children and releases its\nlease on the next heartbeat (within 15 seconds, plus shutdown time). Always run `down`\nbefore intentionally removing a worktree.\n\nA forgotten instance cleans itself up: after 24 hours with no handled Slack turns,\ninteractions, reloads, or restarts, the supervisor tears itself down and frees the slot\non its next idle check (every 10 minutes). Ambient workspace events, health checks,\nstatus reads, and canaries (including `dev doctor`) do not reset the timer. This is\nan idle timeout, not a fixed 24-hour lifetime. It only retires instances running this\nsupervisor; extra connections on another host must be stopped on that host. `DEV_INSTANCE_IDLE_HOURS` overrides the timeout; `0` disables it.\n\n## Real by Default\n\nThe dev instance should exercise the real system:\n\n- real LLM: needs a model credential for the harness you run. Core supports\n  `HARNESS=pi|claude`; the launcher runs Pi when it finds an Anthropic key and honours an\n  explicit `HARNESS=claude`. Pass `DEV_INSTANCE_ALLOW_MOCK=1` for a deliberate no-model\n  wiring check. Pi's GPT models can also use a ChatGPT subscription: set `CODEX_AUTH_FILE`\n  to a local Codex CLI `auth.json`. The auth-file path is for local dev instances; deployed\n  production processes use an API key or a keychain credential (`CODEX_AUTH_CREDENTIAL` \u002F\n  `CLAUDE_AUTH_CREDENTIAL`), whose secret lives encrypted in its owner's keychain.\n- real durability: uses `DATABASE_URL` when supplied; otherwise starts\u002Freuses a local\n  Docker Postgres container and runs core with `SESSION_STORE=postgres` and\n  `RUN_STORE=postgres`\n- production data is never copied into a dev instance\n- captured model context: request capture is on unless overridden, so you can read back what the model was actually sent\n- fast local edits: runs Node surfaces with `--watch` and serves the web UI through\n  Vite HMR on the dev surface instead of a separate browser build loop\n- stale pool recovery: `status` shows each deploy's start time and age; if all pool\n  apps are taken, `up` reclaims a slot not started today or older than 4 hours\n- local admin seed: for a self-provisioned local DB, empty `admin_grants` are seeded\n  from `DEV_INSTANCE_ADMIN_PRINCIPAL` or the local OS user; explicit `ADMIN_GRANTS`\n  still wins\n- local portal auth: the launcher sets a localhost-only portal auth bypass, signing in\n  as `DEV_INSTANCE_ADMIN_PRINCIPAL`, the first `ADMIN_GRANTS` principal, the first\n  durable `org_admin` in Postgres, or the local OS user. Production portal auth remains\n  real OIDC.\n\nOnly use escape hatches for deliberate wiring checks — this is how you ask for _less_ than\nthe full real stack when a test doesn't need it:\n\n```bash\nDEV_INSTANCE_ALLOW_MOCK=1 bash scripts\u002Fdev-instance.sh up\nDEV_INSTANCE_ALLOW_MEMORY=1 bash scripts\u002Fdev-instance.sh up\nDEV_INSTANCE_WATCH=0 bash scripts\u002Fdev-instance.sh up\nDEV_INSTANCE_RECLAIM_STALE=0 bash scripts\u002Fdev-instance.sh up\n```\n\n## Env Discovery\n\nThe launcher reads values from, in priority order: exported shell env, the machine-global\n`~\u002F.config\u002Fqm\u002Fdev.env`, your login shell (for a model credential exported there), and this\nworktree's `.env` (seeded from the main checkout in linked worktrees). Slack pool tokens\ndefault to `~\u002F.config\u002Fqm\u002Fslack-pool`.\n\nWhen a cloud sandbox backend is configured it also validates that provider's access at\nstartup, refreshes a stale provider token from the provider CLI's own logged-in session\nwhere it can, and — if a tunnel binary is present — opens a quick tunnel so sandbox\nself-API calls can reach your local core. None of that runs on the default local backend.\n\n## After Startup\n\nReport the slot, enabled surfaces, their URLs or Slack handle, and log directory. To test Slack-specific\nbehavior, DM the printed `@\u003Chandle>` (on Alice's machine that's one of `@bot1 … @bot10`)\nin `example.slack.com`; for admin and web behavior, open the printed portal URL. Keep\nreview instances running until the PR merges. After merge, run\n`bash scripts\u002Fdev-instance.sh down` from that worktree with the same pool-store override\nused for `up`, before removing the worktree. Verify the instance's supervisor and children\nhave exited and its lease is released. Keep shared Postgres and persistent data intact.\nIf the user asks to keep the instance beyond merge, retain its worktree too. For work\nwithout a PR, tear down when QA is finished unless the user requested a running demo.\n\n## Troubleshooting\n\n**Start with `dev doctor` (or `doctor --json`).** It runs the checks that used to take a\ndebugging session by hand — socket exclusivity (`num_connections`), a live canary\nround trip, env\u002Fgit drift since boot, per-child health and restart counts, stale leases,\nport squatters, machine-wide token orphans, Docker daemon — and prints a ranked diagnosis\nwith a remedy per finding. `doctor --fix` applies the safe ones (child restarts).\n\n**Bot never replies to a DM (silent bot).** The new `up` catches the two big causes at\nboot: multiple reported connections to the same app (flags the slot and auto-rotates)\nand a Slack app whose events never arrive (canary fails → flags the slot and rotates).\nCheck local processes and other deployments before attributing a connection count to\na live competitor. After cleanup, reconnect to obtain a fresh hello count; rereading\nhealth alone returns the previous snapshot. The 10s health probe logs\n`DEGRADED: num_connections=N` in `supervisor.log` when it observes a count transition\nabove one, but cannot detect a new competitor while the hello snapshot is unchanged.\nPeriodic canaries can detect delivery loss; `dev canary` tests delivery on demand.\nA successful canary does not establish exclusivity. `dev up --rotate` moves to a fresh slot.\n\nFor a slot flagged `canary-failed`, check networking, event subscriptions, permissions,\nand competing connections first. If the app configuration needs rebuilding, use\napi.slack.com **signed into the example workspace** (the dev console is\nper-workspace-identity — use \"Sign in to another workspace\" if it lists the wrong one):\nCreate New App → From a manifest → paste `src\u002Fslack\u002Fmanifest.json` (give it a unique\n`name` and bot `display_name`; old handles stay taken) → Install to Workspace → Basic\nInformation → App-Level Tokens → Generate with the `connections:write` scope. Write the Bot\ntoken (`xoxb-…`) and app-level token (`xapp-…`) into `poolN.env`, delete `poolN.flag.json`,\nthen run `up` again to verify the replacement. Reinstalling an existing app may also\nresolve configuration drift; verify delivery afterward.\n\nTwo smaller gotchas: a freshly-created bot isn't in Slack's \"New message\" people search for a\nminute or two — open its DM deterministically via `conversations.open` (bot token + your user\nid) and navigate to `app.slack.com\u002Fclient\u002F\u003Cteam-id>\u002F\u003CD-channel-id>`. And the browser's Slack\nlogin drops easily during long automated sessions; re-authenticating is a Google SSO you have\nto complete yourself.\n",{"name":5,"description":7},"main","db9a120851b734a992a89da1b0e28e7601d13c96",".codex\u002Fskills\u002Fdev-instance",0,"https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi","https:\u002F\u002Fgithub.com\u002Firisfeng","2026-11-05 23:48:35",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add irisfeng\u002Fmoqi --skill dev-instance",{"tool":36,"command":37},"bunx","bunx skills add irisfeng\u002Fmoqi --skill dev-instance",{"tool":39,"command":40},"pnpm","pnpm dlx skills add irisfeng\u002Fmoqi --skill dev-instance","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fdev-instance\u002FSKILL.md",true,[44],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"agents\u002Fopenai.yaml","REFERENCE","参考文档",182,"https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fdev-instance\u002Fagents\u002Fopenai.yaml",[51,58,65,72,80,87],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":18},"01M7F0ME11J9MZ990P1ER4QFG1","use-shared-credential","When you need to call a service the org has a SHARED credential for (a SERP\u002Fsearch key, a paid-API key, a data-vendor feed, a Git remote) — and the platform has told you that credential is available to this conversation — make the call BY PROXY through the credential broker. You never see the secret; the core stamps it onto the outbound request for you.","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Fuse-shared-credential\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":18},"01M7F0M8YEKARSRN8CNED2EBC2","ui-state","See what the person is looking at in the QM web UI right now — the whole page (sidebar, every multiview pane, open dialogs) as raw HTML, the app's state as JSON, optionally the CSS and a screenshot. Use when they ask about something on their screen, want help with the UI, or you need to check what a canvas you wrote actually rendered.","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Fui-state\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M7F0M60MYM1D22BE0N3K1B6F","ui-canvas","Draw your own HTML\u002FCSS\u002FJS as a full-window overlay on top of the QM web UI — a dashboard, a form, a visualization, controls that message you back. Write, update, replace, pin or dismiss it. Use when an interactive or visual result beats a chat reply.","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Fui-canvas\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":76,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M7F0M2G0VJGEZVXH2SB8BM4C","taste-skill","Design taste and process for anything a person will look at in a browser — landing page, dashboard, prototype, deck. The default design driver for a browsable artifact, with an anti-slop playbook for the visual language.","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Ftaste-skill\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Ftaste-skill\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M7F0M03DP690MGQB3H3HW559","slack-drafts","Create Slack message drafts in the user's own composer, as the user, through their per-user Slack OAuth. Drafting only — the user reviews and sends from Slack.","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Fslack-drafts\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":18},"01M7F0KY1M0GGBQJP6WGRMW73T","send","Make a PR, wait for CI with bounded transport retries, independently review, and merge only when all gates pass.","https:\u002F\u002Fgithub.com\u002Firisfeng\u002Fmoqi\u002Fblob\u002Fmain\u002Fskills-seed\u002Fsend\u002FSKILL.md",[],[]]