Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework by jonastemplestein · Pull Request #1411 · iterate/iterate

jonastemplestein · 2026-06-09T23:48:47Z

Golden-path `apps/os`: TanStack Start + oRPC + Cloudflare Workers

Relentlessly simplifies apps/os onto the golden path, fixes the phantom
/projects/new route the sidebar linked to, and — found during review —
closes a live production secret leak. Full decision log:
apps/os/docs/simplification-decisions.md.

1. The bug that started this: a sidebar link to a 404

The sidebar linked to /projects/new, which 404'd. The route file was:

// routes/_app/projects/[_]new.tsx   (the [_] escapes a leading underscore)
export const Route = createFileRoute("/_app/projects/_new")({ ... });

In routeTree.gen.ts this produced a route with path: '' — a pathless
route that the type system still advertised as the linkable target
/projects/new, so <Link to="/projects/new"> typechecked but never matched
at runtime. It hit an upstream router-generator bug with escaped underscores
under a pathless layout (TanStack/router#7408, #7453), and the version we were
pinned to (@tanstack/react-start@1.167.5 → bundled router-generator@1.166.17)
predated the fix.

Why it was bad: typed-but-unmatchable routes are invisible to CI — tsc
passes against a lie. The only way to catch it is to keep the generated route
tree honest.

Fix:

Renamed to a top-level routes/_app/new-project.tsx → /new-project
(also can't ever collide with a $projectSlug).
Bumped the TanStack pair to the version with the generator fix
(react-start 1.168.25 / react-router 1.170.15, bumped together because
react-start hard-pins react-router).
Added scripts/generate-route-tree.ts + routes:check, wired into
typecheck, so CI now fails on a stale/phantom route tree:

// regenerates routeTree.gen.ts with the SAME generator + config the vite build
// uses; --check restores the file and exits 1 if it drifted.
const before = readFileSync(routeTreePath, "utf8");
try { await new Generator({ config, root }).run(); after = readFileSync(routeTreePath, "utf8"); }
finally { if (checkOnly) writeFileSync(routeTreePath, before); }
if (before !== after && checkOnly) { console.error("routeTree.gen.ts is stale…"); process.exit(1); }

2. Removed the "apps framework" over-abstraction

apps/os predated the decision to make OS the only product app. It still paid
for generality it no longer needs.

2a. `app.ts` (manifest + config) → `config.ts`; manifest deleted

A manifest object existed only to parameterize shared helpers by app identity.
With one product app, every consumer can just say "os":

// before — alchemy.run.ts
const ctx = await initAlchemy(manifest, AppConfig, env);
// after
const ctx = await initAlchemy("os", AppConfig, env);

// before — withEvlog took the whole AppManifest
withEvlog({ request, manifest, config, executionCtx }, …)
// after — a plain { name, slug }; log field names kept stable for dashboards
withEvlog({ request, app: { name: "@iterate-com/os", slug: "os" }, config, executionCtx: ctx }, …)

Config utilities (redacted/publicValue/parseAppConfigFromEnv/
extractPublicConfigSchema) and request logging moved out of the apps/*
namespace to @iterate-com/shared/config and @iterate-com/shared/evlog. The
old @iterate-com/shared/apps/* paths are now one-line re-export shims, so
apps/semaphore needs zero changes in this PR.

2b. `AppContext` (hand-threaded) → `RequestContext` (TanStack Start's own)

The old AppContext carried every worker binding as an optional field,
threaded around next to — not through — TanStack Start's request context. That
forced a defensive guard at every use site for bindings that are always bound:

// before — in ~6 routers/capabilities
if (!context.stream) {
  throw new ORPCError("INTERNAL_SERVER_ERROR", { message: "STREAM … not configured." });
}
const ns = context.stream as unknown as StreamDurableObjectNamespace;

Why it was bad: a dozen impossible-error branches, an AppContext type
listing 14 optional bindings, and two parallel notions of "context". The
golden-path answer is to read bindings where you use them:

// after — env is the documented module-level binding accessor
import { env } from "cloudflare:workers";
const ns = env.STREAM as unknown as StreamDurableObjectNamespace;

RequestContext (src/request-context.ts) is now just request-scoped state
(config, db, log, auth principal/session, waitUntil, ctx.exports, project
scope) and is the actual TanStack Start request context — the Register
augmentation lives next to the type. ctx.exports is the one binding kept on
the context, because Cloudflare only exposes it on ExecutionContext, not as a
module import.

Net effect on the routers: agents +10/−44, projects +22/−52,
codemode +3/−21, streams +5/−14 — they all got smaller.

2c. `entry.workerd.ts` (604 lines) → `worker.ts` (197 lines) + focused modules

The entrypoint was a 600-line grab-bag. It's now a short, linear dispatcher a
Cloudflare engineer would recognize at a glance — infra routes → evlog →
project ingress → stream RPC / capnweb → TanStack Start handler:

export default {
  async fetch(request, env, ctx) {
    const config = parseConfig(env); // per-request, not module scope — see §3 note
    const early = (await handleCaptunTunnelFetch(request, env, config))
      ?? (await handleDebugRoutes({ request, env, config }));
    if (early) return early;
    return withEvlog({ request, app: { name: "@iterate-com/os", slug: "os" }, config, executionCtx: ctx },
      async ({ log }) => {
        // … ingress → stream RPC → capnweb → handler.fetch(request, { context }) …
      });
  },
};

The debug endpoints, project-stream RPC, and ingress lookup moved into
src/debug-routes.ts, src/domains/streams/project-stream-rpc.ts, and
src/ingress/lookup.ts. IterateApp gained a main option (default unchanged,
so semaphore is untouched). The __internal oRPC namespace and the OpenAPI
reference plugin are now declared inline in orpc/root.ts / orpc/handler.ts
instead of via a shared factory.

3. 🔒 Security: closed an unauthenticated secret leak (rotate secrets)

Review turned up that GET /api/__internal/debug was unauthenticated and
returned process.env — which, under nodejs_compat (always on for our
workers), contains the raw APP_CONFIG secret blob. Confirmed live on
os.iterate.com and semaphore.iterate.com.

// before — packages/shared/src/apps/internal-router.ts
export function createInternalDebugOutput() {
  if (typeof process === "undefined") return { runtime: "workerd" };
  return { runtime: "node", pid: process.pid, …,
    env: Object.fromEntries(Object.entries(process.env)…), // ← the whole secret blob, to anyone
    memoryUsage: process.memoryUsage() };
}
// after
export function createInternalDebugOutput() {
  // SECURITY: this route is UNAUTHENTICATED. Never return secrets here.
  return { runtime: "workerd" as const };
}

Gutted at the shared source so semaphore (still on the shared router) is fixed
too; OS's inline __internal router does the same.

Access check (Cloudflare Workers Observability, queried 2026-06-10): a path
filter url.path eq /api/__internal/debug returned 0 events; the only
__internal traffic was trpc-cli-procedures from our own node CLI. That's
reassuring but not proof — effective visibility for rare requests was only
~the last 24–35h (far shorter than the exposure window) and the dataset is
ABR-sampled. Action required: rotate the Cloudflare API token, OpenAI/xAI/
Gemini keys, admin API secret, and Slack/Google OAuth secrets on both apps, then
redeploy.

Note (also from review): config is now parsed per request in worker.ts,
not at module scope. Module-scope derivatives of secrets can go stale across
binding-only deploys (Cloudflare reuses isolates); a zod parse per request is
trivially cheap and always honors the current secret.

4. Review & verification

Two adversarial reviews against re-read first-party docs (Cloudflare,
TanStack Start/Router/Query, oRPC). They caught, among other things, a
build blocker — @tanstack/devtools-vite@0.7.0's removeDevtools
transform rewrites a parenthesized JSX return into return ( ); (a syntax
error), which only vite build (deploy/preview) surfaces, not PR CI. Pinned
back to 0.6.0.
Monorepo typecheck / lint (0 warnings) / format / tests / a real
vite build all pass; Cursor Bugbot clean; Preview deploy + e2e green.
Headless preview smoke test (apps/os/docs/preview-agent-browser-smoke.md):
superadmin sign-in → create a project via /new-project → a real agent
conversation (typed a question in the browser, the agent DO + LLM replied).

Two honest caveats are documented, not hidden: a transient Project not found
I chased was an expired short-lived OS session JWT, not a bug; and live
stream display needs a WebSocket that 500s on preview hosts (the conversation
completes server-side; the WS-upgrade code is byte-identical to main → flagged
as preview-infra follow-up, not claimed fixed).

5. "Wait, a simplification PR that's net +~930 lines?"

Correct, and worth unpacking — because ~74% of the net isn't application code
at all, and the code that is application logic mostly shrank.

git diff origin/main…HEAD: 91 files, +3709 / −2777 = net +932. By area:

Area	net	what it is
`pnpm-lock.yaml`	+423	dependency-graph churn from the TanStack version bump. Zero hand-written lines.
`docs/`	+267	the decisions log + headless smoke-test guide you asked for. Prose, not code.
`apps/os/src`	+123	see below — dominated by new files that replace deleted ones
`scripts/`	+61	the new `generate-route-tree.ts` freshness check (pure addition, didn't exist)
`packages/shared`	+57	back-compat shims so semaphore is untouched + the moved modules
generated `routeTree.gen.ts`	0
tests / other	+1

pnpm-lock.yaml + docs alone are +690 of the +932. Strip those and the
real source delta is ~+240, almost all of it deliberate new
infrastructure, not retained complexity:

generate-route-tree.ts (+61) — new CI guard against the class of bug that
started this PR.
request-context.ts (+96) + router-context.ts (+18) — replace the deleted
context.ts (−51) with a smaller, correct request context plus the typed
accessors that work around an upstream getGlobalStartContext type bug.
back-compat shims in packages/shared/src/apps/* — a few lines each so
semaphore changes by zero lines instead of forcing a parallel refactor
into this PR.

The actual product logic got smaller and flatter:

entry.workerd.ts (−604) → worker.ts (+197) plus three focused extracted
modules. The headline file shrank ~3×.
the oRPC routers lost net ~120 lines of impossible-error binding guards.
context.ts (−51) and the 14-field AppContext are gone.

The line counters also double-count pure moves: config.ts shows as
+501 (new path) and −501 (old path → 4-line shim) — net ~0 churn that
inflates both columns. Same for the evlog modules. Git doesn't detect these
as renames because the old path still exists as a shim.

So: net +~930, but it's lockfile (+423) + requested docs (+267) + new guard
rails and a security fix (+~240), against genuinely less and simpler runtime
code. If you want the "pure simplification" number, it's the apps/os/src
runtime logic, which is net-negative once you exclude the new context/worker
scaffolding that replaced larger deleted files.

🤖 Generated with Claude Code

6. Update: merged `main` (itx) + semaphore migration

Since this branch opened, main landed #1407 (itx) which rewrote the worker
entrypoint and replaced src/capnweb/ with src/itx/. Rather than rebase
through it, I merged main and reconciled:

worker.ts now wires the itx handlers (handleItxFetch,
handleProjectHostItxFetch, getItxCapHostIngressRule, itx entrypoint
exports) instead of the removed capnweb ones — keeping the clean split
(debug-routes.ts, project-stream-rpc.ts, ingress/lookup.ts).
The whole src/itx/ subsystem was migrated onto the new config.ts /
request-context.ts (it was built on the now-deleted app.ts/context.ts).
Honored main's new no-raw-durable-object-binding-access guardrail:
ingress code (projects router, integration-api) mints Project/Slack DO stubs
through helpers in the trusted *-durable-object.ts domain files
(getProjectDurableObjectStub, getSlackIntegrationStub) rather than raw
env.X.getByName. Updated the rule's allowlist for the worker.ts rename.

Also migrated apps/semaphore off the same @iterate-com/shared/apps/*
framework (its own app.ts→config.ts, context.ts→request-context.ts,
entry.workerd.ts→worker.ts, inline __internal), which let me delete the
shared modules entirely (the apps/config, apps/logging/*,
apps/internal-router, apps/orpc shims) instead of leaving them as
back-compat shims. Monorepo typecheck, lint (0 warnings), and tests are green.

Note

High Risk
Removes the shared apps layer and rewrites the worker entry, request context, and oRPC wiring across most of OS; also fixes a live unauthenticated debug endpoint that exposed secrets—rotate affected credentials after deploy.

Overview
Refactors apps/os off the shared “apps framework” onto a single-app golden path: app.ts → config.ts, AppContext → RequestContext (TanStack Start’s registered request context), and entry.workerd.ts → worker.ts with logic split into debug-routes.ts, ingress/lookup.ts, and project-stream-rpc.ts. oRPC routers and integrations now read Cloudflare bindings via import { env } from "cloudflare:workers" instead of optional fields on context, with trusted DO stub helpers for lint compliance.

Fixes the phantom /projects/new route by moving project creation to /new-project, bumps the TanStack pair, and adds routes:check / generate-route-tree.ts so CI fails on a stale routeTree.gen.ts.

Security: stops GET /api/__internal/debug from exposing secrets — OS inlines a safe __internal router (static { runtime: "workerd" } on debug) and hardens the shared debug helper so other apps don’t leak process.env.

Docs add the simplification decision log and expanded headless preview smoke procedures; alchemy deploy points IterateApp at ./src/worker.ts and passes "os" to initAlchemy instead of a manifest.

^{Reviewed by Cursor Bugbot for commit ecbd6d7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Environment Config Lease

No active environment config lease.

OS

Status: released
Commit: ecbd6d7
Preview: https://os.iterate-preview-2.com
Summary: Preview app released.
Workflow run
Updated: 2026-06-10T08:12:17.757Z

Semaphore

Status: released
Commit: ecbd6d7
Preview: https://semaphore.iterate-preview-2.com
Summary: Preview app released.
Workflow run
Updated: 2026-06-10T08:12:13.352Z

…ade TanStack Start - routes/_app/projects/[_]new.tsx generated a pathless route that typed as linkable (/projects/new) but never matched at runtime (404 from the sidebar). Renamed to routes/_app/new-project.tsx -> /new-project, which also can't collide with project slugs. Links updated. - New scripts/generate-route-tree.ts regenerates routeTree.gen.ts with the same @tanstack/router-generator + config the vite build uses; `routes:check` fails when the committed tree is stale and runs as part of `typecheck`, so CI catches stale/phantom route trees. - Upgraded @tanstack/react-start 1.167.5 -> 1.168.25 (+ react-router 1.170.15, devtools 1.167.0, ssr-query ^1.167.1, devtools-vite ^0.7.0). The old pinned pair bundled router-generator 1.166.17, which predates the upstream fixes (TanStack/router#7408, #7453) for exactly this escaped- underscore phantom-route bug class. - Audit fixes per latest start-basic reference: notFoundComponent on the root route, scrollRestoration on the router. - Sidebar: Repl now sits in its own group below a separator instead of inside the projects block. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…framework apps/os no longer uses the @iterate-com/shared/apps/* framework: - src/app.ts (manifest + AppConfig) becomes src/config.ts; the manifest concept is gone. Shared config utilities moved to @iterate-com/shared/config and request logging to @iterate-com/shared/evlog (old apps/* paths remain as re-export shims so apps/semaphore is untouched). - entry.workerd.ts becomes worker.ts: a linear dispatcher (infra routes -> evlog -> project ingress -> stream RPC/capnweb -> TanStack Start handler). Debug endpoints move to src/debug-routes.ts, project-stream RPC to src/domains/streams/project-stream-rpc.ts, ingress lookup to src/ingress/lookup.ts. IterateApp gains a `main` option. - AppContext becomes RequestContext (src/request-context.ts) - the TanStack Start request context, holding request-scoped state only. Worker bindings are read via `import { env } from "cloudflare:workers"` at point of use, deleting a dozen "binding not available" guards. - The __internal oRPC namespace (CLI discovery, publicConfig) is implemented inline in orpc/root.ts; the OpenAPI reference plugin is instantiated directly in orpc/handler.ts. - The new Start plugin appends a Register footer to routeTree.gen.ts (ssr/router/config). scripts/generate-route-tree.ts mirrors it so routes:check stays byte-identical with the build. Keeping route types acyclic required: lambda-wrapped router components, RouterContext in its own module, server functions outside routes/, and registering requestContext on both react-start's and react-router's Register (different consumers read different interfaces). getGlobalStartContext's collapsed return type (upstream bug) is wrapped by typed accessors in request-context.ts. - iterateAuthMiddleware is now createMiddleware({ type: "request" }), the correct contract for requestMiddleware that returns raw Responses. See apps/os/docs/simplification-decisions.md for the full decision log. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Security (CRITICAL, pre-existing): GET /api/__internal/debug was unauthenticated and returned process.env, which under nodejs_compat contains the raw APP_CONFIG secret blob — confirmed leaking live on os.iterate.com and semaphore.iterate.com. Gutted the shared createInternalDebugOutput to return only { runtime: "workerd" } so semaphore (still on the shared router) stops leaking too; os's inline router already did. Secrets must be rotated — see apps/os/docs/simplification-decisions.md §6. Build blocker: @tanstack/devtools-vite 0.7.0's removeDevtools transform rewrites a parenthesized JSX return into `return ( );` (syntax error), failing `vite build` — which PR CI (lint/typecheck/test) never runs, so only a deploy would catch it. Pinned back to 0.6.0 (dev-only tooling, no runtime change). Verified `vite build` now succeeds. Other review fixes: - worker.ts parses config per request instead of at module scope, so binding-only deploys that rotate secrets are honored without isolate recycling (matches the capnweb per-request parsing). - /__durable-objects/* debug proxy is now admin-bearer gated. - root-auth-snapshot / public-route-config use requireRequestContext (loud failure) instead of silently degrading to signed-out/empty config. - requireRequestContext typed param; dead baseUrl ternary removed; requireStreamNamespace misnomer inlined; doc Awaited<> accuracy. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Document the bootstrap-superadmin email/password login (no OAuth provider / no CDP prompt) so agent-browser smoke tests can run fully unattended. Removes the standalone headless-browser-smoke-testing.md in favor of a section in the existing smoke doc. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ocedure Verified the PR preview end to end with a headless browser: superadmin sign-in, project creation via /new-project, and a real agent conversation (agent replied through the DO+LLM, confirmed via UI and runtime-state). The security fix is live on the preview. Corrects the smoke-test doc: the hosted login UI only offers Google, so unattended auth goes through the better-auth sign-in API + cookie injection + consent (not a form fill). Documents two gotchas: transient "Project not found" = expired short-lived OS session JWT (not a bug), and live stream display needs WebSocket which 500s on preview hosts (WS code unchanged from main; flagged as preview-infra follow-up). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

With os already migrated, semaphore was the only remaining consumer of the @iterate-com/shared/apps/* framework (kept alive by back-compat shims). This moves semaphore onto the same golden path and then deletes the abstraction: semaphore: - src/app.ts (manifest + config) -> src/config.ts; manifest gone, parseConfig helper added; config/redacted/publicValue come from @iterate-com/shared/config. - src/context.ts AppContext -> src/request-context.ts RequestContext. - src/entry.workerd.ts -> src/worker.ts; withEvlog from @iterate-com/shared/evlog with app:{name,slug}. - __internal oRPC namespace implemented inline in orpc/root.ts; OpenAPI reference plugin inlined in orpc/handler.ts (adds trpc-cli + @orpc/zod deps, matching os). __internal.debug returns only { runtime } — no process.env. - __root.tsx / seed script use @iterate-com/shared/config; alchemy.run.ts passes the "semaphore" slug and main: ./src/worker.ts. shared (now unused -> deleted): - src/apps/config.ts (shim), src/apps/logging/* (5 shims), src/apps/internal-router.ts, src/apps/orpc.ts, and their package.json exports. - alchemy/init.ts drops the AppManifest overload (callers pass a slug string). Kept (still legitimately shared): apps/internal-router-contract, apps/openapi, apps/cli, apps/new-style-cloudflare-apps, apps/types (AppContext generic used by evlog/runtime). Monorepo typecheck + lint (0 warnings) + os/shared tests all pass. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

# Conflicts: # apps/os/package.json # apps/os/src/capnweb/e2e/captnweb-slack-sdk.e2e.test.ts # apps/os/src/capnweb/e2e/captnweb.e2e.test.ts # apps/os/src/capnweb/iterate-context-capability.ts # apps/os/src/capnweb/project-capability.ts # apps/os/src/capnweb/repos-capability.ts # apps/os/src/capnweb/root-context-fetch.ts # apps/os/src/capnweb/streams-capability.ts # apps/os/src/capnweb/workspace-capability.ts # apps/os/src/components/app-sidebar.tsx # apps/os/src/domains/projects/durable-objects/project-durable-object.ts # apps/os/src/domains/projects/project-directory.ts # apps/os/src/entry.workerd.ts

# Conflicts: # apps/os/src/domains/agents/durable-objects/agent-durable-object.ts # apps/os/src/domains/codemode/example-capabilities.ts # apps/os/src/domains/google/entrypoints/gmail-capability.ts # apps/os/src/domains/projects/project-directory.ts # apps/os/src/domains/secrets/entrypoints/secrets-capability.ts # apps/os/src/domains/slack/durable-objects/slack-integration-durable-object.ts # apps/os/src/entry.workerd.ts # pnpm-lock.yaml

…c/export cleanup Three post-merge adversarial reviews found the refactor complete and regression-free in apps/os; this addresses the "unfinished business" they flagged: - semaphore now follows the same `import { env } from "cloudflare:workers"` principle as os: dropped `env` from its RequestContext and read RESOURCE_COORDINATOR/DB at point of use (orpc/root.ts + the resources SSR route). Removes the env-on-context inconsistency between the two apps. - knip.ts: the shared TanStack-app workspace `entry` still named the renamed `src/entry.workerd.ts`; pointed it at `src/worker.ts` (covers os + semaphore). - Removed a dangling `./apps/middleware/require-header` export (nonexistent file) from packages/shared/package.json. - Fixed stale `entry.workerd.ts` references in itx/README.md and the capability design-notes doc (the DO-binding rule allowlist now lists worker.ts). Monorepo typecheck, lint (0 warnings), and tests all green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The apps/semaphore config migration rewrote AppConfig as a fresh z.object({...}) instead of BaseAppConfig.extend({...}), silently dropping the inherited baseUrl field. alchemy's IterateApp derives the worker route and proxied DNS from runtimeConfig.baseUrl (deriveWorkerRouteHosts); with baseUrl undefined it created no route, so semaphore.<base> resolved via DNS but had no worker bound and Cloudflare answered 522. That 522 failed the preview readiness poll and reported as a generic "Failed to deploy" — the os worker itself was healthy throughout. Restore baseUrl: publicValue(z.url().optional()) (the Doppler config already supplies APP_CONFIG_BASE_URL). Document the diagnosis in the decisions log. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit ecbd6d7. Configure here.}

- tasks/cf-prd-orphaned-resources-cleanup.md: completed — prd account is down to 14 worker scripts and 6 D1 databases per live 2026-06-10 Cloudflare API check (was 1026 at the 2026-05-18 sweep) - tasks/complete/2026-05-22-os-captun-worker-test-tunnel.md: completed — shipped via merged PR #1361; all described artifacts exist on main and survived the golden-path rebuild (#1411) - tasks/dead-code-and-docs-cleanup-audit.md: completed — all high-confidence items shipped; pnpm-workspace.yaml now uses apps/*/packages/* globs and no longer lists the dead packages - tasks/github-oauth-use-repo-id.md: obsolete — all referenced code (linkExternalIdToGroups / repoId / repository.id) is gone repo-wide - tasks/ignoreme-email-security.md: obsolete — every targeted code path was deleted with the legacy OS1 stack in commit 545854d (#1341) - tasks/os-auth-spurious-logout-refresh.md: completed — commit ad6da76 (#1410, merged 2026-06-10) shipped exactly this work - tasks/os-codemode-router.md: completed — task file was added in the very PR that implemented it (commit 98ee148, #1294) - tasks/os-domain-capability-orpc-refactor-design.md: completed — every major pillar of the design (domains layout, capabilities, oRPC structure) exists on main - tasks/os-domain-capability-orpc-refactor-prd.md: completed — shipped in PR #1305 "Make codemode function calls event-driven" (squash commit 284193e, merged 2026-05-08) - tasks/os-stream-runtime-big-refactors.md: obsolete — os2-era brainstorm list largely superseded or done differently; item 2 shipped via PR #1394 - tasks/realtime-pusher-efficiency.md: obsolete — targets the legacy OS1 realtime pusher, which no longer exists - tasks/semaphore-lease-renewal.md: completed — lease renewal exists on main as resources.renew in apps/semaphore - tasks/signup-slug-uniqueness.md: completed — shipped with the auth worker (PR #1273); packages/shared/src/slug.ts implements resolveUniqueSlug/slugifyWithSuffix - tasks/stream-processor-ergonomics.md: obsolete — targets the legacy hook-style processor API replaced by the class-based StreamProcessor model - apps/os/tasks/codemode-session-night-plan.md: completed — planned outcomes verifiably shipped on main in evolved form (codemode session UI and friends) - apps/os/tasks/codemode-session-vertical-slice.md: completed — all 11 ticked checklist items shipped via PRs #1294/#1305 and follow-ups - apps/os/tasks/refactor-lifecycle-init-params-as-structured-name.md: completed — every acceptance criterion implemented in with-lifecycle-hooks.ts mixin on main - apps/os/tasks/repos-vertical-slice.md: completed — frontmatter says state: done and the described slice exists on main - apps/os/tasks/slack-google-auth-poc-implementation.md: historical log — explicitly an implementation log (state: done); work shipped in merged PR #1317 - apps/os/tasks/slack-processor-unwind.md: completed — all target-shape items exist on main (/integrations/slack stream path, no webhooks refs) - apps/os/tasks/stream-processor-class-design-notes.md: historical log — design notes written alongside the class-based StreamProcessor migration, not a task - apps/os/tasks/workspace-codemode-implementation-log.md: historical log — frontmatter state: done, all 9 checkpoints ticked, work verifiably shipped on main Already deleted by earlier commits on this branch (skipped): apps/os/tasks/project-egress-secrets-mvp.md, apps/os/tasks/simplify-context-cloudflare-native.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…capnweb pointers, fix task states (#1432) Documentation sweep over `apps/os`. Every statement written into a doc was verified against the code on this branch. ## Changes **`apps/os/README.md` (= `AGENTS.md`)** - Important Files: `src/app.ts` / `src/entry.workerd.ts` do not exist — replaced with `src/worker.ts` (Worker entrypoint) and `src/config.ts` (`AppConfig` schema). All other listed files verified to exist. - Real-worker tests: the documented vitest configs (`src/capnweb/e2e/vitest.config.ts`, `src/domains/capability-prototype/e2e.vitest.config.ts`) are gone — replaced with the real lanes `pnpm e2e` (`e2e/vitest.config.ts`) and `pnpm e2e:itx` (`src/itx/e2e/vitest.config.ts`), verified against `apps/os/package.json`. - `pnpm cf:deploy # production deploy` was wrong and dangerous: `cf:deploy` deploys to whatever Doppler/Alchemy stage is ambient. Now documents both `cf:deploy` (ambient stage) and `pnpm deploy` (the `doppler --config prd` wrapper). - Removed the nonexistent `/org/:organizationSlug` route; remaining routes verified against `src/routes/`; added `/new-project`. **`apps/os/CONTEXT.md`** — fixed the example-dialogue claim that organization UI lives under `/org/:organizationSlug` (no such route; orgs live in the auth worker). **`apps/os/docs/architecture-and-operations.md`** — rewritten. The old doc described the pre-migration world: Clerk auth (whole `## Clerk` section, `sync-clerk-apps.ts`, `APP_CONFIG_CLERK__*`), `/orgs/:organizationSlug` route maps, inbound MCP via `ProjectMcpServerEntrypoint` (now a hardcoded 410 tombstone), wrong redirect claims, and an unprefixed `/durable-objects/stream` debug route. The new doc describes current reality: `src/worker.ts` dispatch pipeline, Iterate Auth middleware, real route map and root-redirect behavior (`/` → `/projects/$projectSlug` or `/projects`; project root renders `ProjectHomePage`), canonical MCP endpoint from `APP_CONFIG_MCP__BASE_URL` with Iterate Auth protected-resource metadata, `/__durable-objects/<kind>/<name>/<path>` debug proxy (kinds verified), itx endpoints, `scripts/sync-auth-clients.ts`, current codemode default/example providers, and current smoke-test env vars (verified in the e2e test files). **`apps/os/docs/headless-local-debugging.md`** — `/projects/new` → the real route `/new-project`. **`apps/os/docs/iterate-context.md`, `iterate-context-learnings.md`** — both pointed at the deleted `src/capnweb/` tree as "the current design"; now short tombstones pointing at the successor (`src/itx/` README + DECISIONS, `docs/itx-spec.md`). **`apps/os/docs/capability-system-research-and-design-notes.md`, `rpc-target-constructor-shape-research.md`** — added status headers marking them historical research notes superseded by itx; bodies untouched. **`apps/os/src/itx/README.md` + `src/itx/handle.ts`** — the "Typed caps" `ProjectCaps` declaration-merging pattern does not exist in code (no `ProjectCaps` interface anywhere). Rewrote the README section to the thing that actually works: casting `itx.cap("name")` through the exported `Stubify<T>` type. Also fixed the same false claim in the `Stubify` doc comment in `handle.ts` (comment-only change). **`apps/os/docs/itx-spec.md`** — status header said "IMPLEMENTED on the `itx-implementation` branch"; PR #1407 is merged to main (verified in git history). Marked the one known divergence honestly: the §6.3 client reconnect loop was never built — `connectItx` (`src/itx/client.ts`) is one-shot, and there is no `itx.cap.disconnected` event. Corrected §6.3 and the related §4 caveat. **`apps/os/tasks/`** - Deleted `simplify-context-cloudflare-native.md` (state: todo, but shipped — `src/worker.ts` imports `env` from `cloudflare:workers` directly, `RequestContext` is the narrow request-scoped shape the task specified, auth lives in Start request middleware, the manifest/`src/app.ts` is gone). - Deleted `project-egress-secrets-mvp.md` (state: todo, but shipped — `ProjectEgress` entrypoint, `ProjectDurableObject.egressFetch` with `substituteProjectEgressSecretHeaders`, D1-backed `SecretsCapability.getSecret`, and the `/api/itx/egress-echo` echo proof covered by `src/itx/e2e/itx-egress.e2e.test.ts`). - Grooming rules (`docs/tasks-grooming.md`) say "Delete when done", so deletion rather than state edits. - Added brief status notes (no rewrite) to `codemode-session-vertical-slice.md` (checked-off "tiny worker" box diverged: `CodemodeSession` lives in the main OS worker) and `codemode-session-night-plan.md` (plan superseded by itx). ## Skipped - Nothing skipped; all nine items verified and addressed. ## Flags for reviewers - `src/itx/handle.ts` got a comment-only edit (the `Stubify` doc comment made the same false declaration-merging claim as the README). No runtime change; typecheck/lint/tests pass. - The two deleted task files: please sanity-check the "shipped" verdicts above if you have more context on intended remaining scope. - Carve-outs respected: no changes to the streams type systems or to how the os-streams worker is deployed. ## Checks - `pnpm install`, `pnpm format` (oxfmt), `pnpm typecheck`, `pnpm lint`, `pnpm test` — all pass. ## Task-file audit A follow-up commit deletes 22 task files whose work was verified as shipped, obsolete, or purely historical. (Two more from the audit — `apps/os/tasks/project-egress-secrets-mvp.md` and `apps/os/tasks/simplify-context-cloudflare-native.md` — were already deleted by earlier commits on this branch, see above.) ### Deleted: completed - `tasks/cf-prd-orphaned-resources-cleanup.md` — live Cloudflare API check of the prd account (2026-06-10) shows 14 worker scripts (was 1026 at the task's 2026-05-18 sweep) and 6 D1 databases; cleanup is done. - `tasks/complete/2026-05-22-os-captun-worker-test-tunnel.md` — shipped via merged PR #1361 ("codemode++ e2e++"); all described artifacts exist on main and survived the golden-path rebuild (#1411). - `tasks/dead-code-and-docs-cleanup-audit.md` — high-confidence items all shipped; `pnpm-workspace.yaml` no longer lists the dead packages and now uses `apps/*`/`packages/*` globs. - `tasks/os-auth-spurious-logout-refresh.md` — commit ad6da76 "Fix 5-min logout, deploy-time JWKS, and stream append skeleton flash (#1410)" (merged 2026-06-10) shipped exactly this work. - `tasks/os-codemode-router.md` — task file was added in the very PR that implemented it (commit 98ee148, #1294). - `tasks/os-domain-capability-orpc-refactor-design.md` — every major pillar of the design (domains layout, capabilities, oRPC structure) exists on main. - `tasks/os-domain-capability-orpc-refactor-prd.md` — shipped in PR #1305 "Make codemode function calls event-driven" (squash commit 284193e, merged 2026-05-08). - `tasks/semaphore-lease-renewal.md` — the described lease-renewal feature exists on main as `resources.renew` (named "renew" rather than the proposed "extend") in `apps/semaphore`. - `tasks/signup-slug-uniqueness.md` — shipped with the auth worker (PR #1273); `packages/shared/src/slug.ts` implements `resolveUniqueSlug`/`slugifyWithSuffix`. - `apps/os/tasks/codemode-session-night-plan.md` — planned outcomes verifiably shipped on main, in evolved form (codemode session browser UI and follow-ons). - `apps/os/tasks/codemode-session-vertical-slice.md` — all 11 ticked checklist items shipped via PRs #1294/#1305 and follow-ups. - `apps/os/tasks/refactor-lifecycle-init-params-as-structured-name.md` — every acceptance criterion implemented in the `with-lifecycle-hooks.ts` mixin on main. - `apps/os/tasks/repos-vertical-slice.md` — frontmatter already says `state: done` and the described slice verifiably exists on main. - `apps/os/tasks/slack-processor-unwind.md` — all target-shape items exist on main (`/integrations/slack` stream path; no `/integrations/slack/webhooks` references). ### Deleted: obsolete / nonsense - `tasks/github-oauth-use-repo-id.md` — all referenced code is gone: `linkExternalIdToGroups` / `repoId` / `repository.id` return zero hits repo-wide. - `tasks/ignoreme-email-security.md` — every code path the task targets was deleted with the legacy OS1 stack (commit 545854d, #1341). - `tasks/os-stream-runtime-big-refactors.md` — os2-era brainstorm list largely superseded or done differently; item 2 shipped via PR #1394. - `tasks/realtime-pusher-efficiency.md` — targets the legacy OS1 realtime pusher, which no longer exists. - `tasks/stream-processor-ergonomics.md` — targets the legacy hook-style processor API, replaced by the class-based StreamProcessor model. ### Deleted: historical logs - `apps/os/tasks/slack-google-auth-poc-implementation.md` — explicitly an "Implementation Log" (`state: done`), not actionable work; shipped in merged PR #1317. - `apps/os/tasks/stream-processor-class-design-notes.md` — design notes written alongside the class-based StreamProcessor migration, not a task. - `apps/os/tasks/workspace-codemode-implementation-log.md` — `state: done`, all 9 checkpoints ticked; the described work verifiably shipped on main. ### Kept but flagged for maintainer judgment - `tasks/cf-prd-orphaned-resources-cleanup.md`: Explicit not-in-scope follow-ups (preview account 376ef7ed cleanup, Doppler os-legacy-backup pruning) were never broken out into their own tasks; spin them out only if still wanted. - `tasks/codemode-capability-policy.md`: Still-unshipped, still-wanted design work, but duplicates `apps/os/tasks/codemode-capability-access-policy.md` and overlaps the active itx capability-system design notes — maintainer should consolidate into a single task. - `tasks/complete/2026-05-22-os-captun-worker-test-tunnel.md`: apps/os still depends on the unpublished pkg.pr.new/captun@14 build (the task's stated stopgap); a published captun/worker release would be a separate follow-up, not a reason to keep this file. - `tasks/dead-code-and-docs-cleanup-audit.md`: Residual from this audit: packages/iterate is still excluded from root build/typecheck/test (`--filter '!iterate'`); if that CI gap matters, open a fresh small task rather than keeping this stale inventory. - `tasks/doppler-shared-and-os-secrets-audit.md`: Audit still unrun and wanted, but needs a rewrite first: replace Clerk-key expectations with iterateAuth, point AppConfig refs at `apps/os/src/config.ts` (`app.ts` and `packages/shared/src/apps/config.ts` were deleted in PR #1411), and refresh the 2026-05-18 baseline. - `tasks/ignoreme-email-security.md`: If outbound email via Resend is ever reintroduced in the rebuilt apps/os, recipient allowlisting should be designed fresh against the itx/egress-secret-substitution layer, not this OS1-era plan. - `tasks/iterate-cli-distribution.md`: Live but ~90% of the file is OpenCode architecture research notes, not actionable steps; npm distribution already exists, so the remaining work (bun binary, brew, install script) should be restated as concrete tasks or the research trimmed. - `tasks/os-auth-spurious-logout-refresh.md`: PR #1410 left one open thread: a manual end-to-end "wait 5 minutes in prod" verification was never done, and the claims-staleness force-refresh was consciously skipped (≤30m propagation accepted) — file a new narrow task only if either still matters. - `tasks/os-deploy-time-jwks-fetch.md`: Code shipped in PR #1410; only remaining action is deleting `ITERATE_AUTH_JWKS` from Doppler os prd/preview (still present and shadowing the deploy-time fetch) — after that, delete this task. - `tasks/os-domain-capability-orpc-refactor-prd.md`: Sibling task `os-domain-capability-orpc-refactor-design.md` (its dependsOn target) is likely also completed and should be audited/deleted together. - `tasks/os-project-do-projection-reconciliation.md`: Scope item "rename IterateMcpServer to ProjectMcpServerConnection" is already done and could be ticked off; the rest is unshipped and still relevant. - `tasks/os-project-hostname-base-singular.md`: Scope file paths are stale post-PR #1411 (`app.ts`→`src/config.ts`, `sync-clerk-apps.ts`→`sync-auth-clients.ts`, `entry.workerd.ts` deleted, routing files moved to `src/ingress/`); task itself is still valid. - `tasks/os-project-route-authorization.md`: Still-wanted design work (referenced by live project-ingress-architecture task), but needs rewrite: Clerk OAuth and `ProjectMcpServerEntrypoint` references are dead — MCP moved off project ingress (410 stub) and auth is now apps/auth Principal-based. - `tasks/os-stream-runtime-big-refactors.md`: Only surviving idea: cosmetic no-compat rename of `events.iterate.com/...` event-type names (events app is deleted); re-file as a small standalone task if still wanted. - `apps/os/tasks/codemode-capability-access-policy.md`: Live work, but near-duplicates root-level `tasks/codemode-capability-policy.md` (same PR #1294); keep this copy and consolidate/delete the root one. - `apps/os/tasks/codemode-session-night-plan.md`: Open capability-scope questions from this plan live on in `codemode-capability-access-policy.md`; checkboxes are unticked but the work shipped via PRs #1294/#1305/#1402. - `apps/os/tasks/codemode-session-vertical-slice.md`: Last unchecked box (generalize self-callable bindings) shipped as the loopback-binding pattern used repo-wide; follow-on work lives in `codemode-session-night-plan.md`. - `apps/os/tasks/project-egress-and-secrets-architecture.md`: Design doc whose first vertical slice shipped (egress + secret substitution MVP); remaining secret-DO/policy/approval/OAuth design is still live but needs grooming: drop completed PoC sections, update Clerk-scope terminology, and reconcile with itx DECISIONS.md as the newer design-of-record for egress wiring. - `apps/os/tasks/project-egress-intercept-tunnel-latency.md`: Still-relevant latency work, but file refs are stale (`entry.workerd.ts` → `src/worker.ts`; vendored `apps/os/src/lib/captun` removed for the published captun package in #1361) and the benchmark numbers predate the #1411 worker rebuild — re-benchmark before picking an option. - `apps/os/tasks/project-ingress-architecture.md`: Live, actively-maintained ingress reference (edited today in #1416), but needs a refresh: Clerk auth sections, `Project.checkAccess`, and the streams-upstream proxy model are superseded (auth worker, principal claims, bundled project worker), and the 2026-05-05 status checklist is partly outdated. - `apps/os/tasks/stream-processor-class-migration-log.md`: Migration log (merged today via #1402, which links to it as the canonical rationale) — not an actionable task; contains unique I6-I8 forensics not in the PR body, consider moving to docs/ alongside `tasks/migration-notes/` rather than deleting. - `apps/os/tasks/stream-subscriber-delivery-refactor.md`: Core design shipped differently via the class-model cutover (#1401/#1402/#1394); only live remainder is migrating `codemode.streamEvents`, `StreamsCapability.stream()`, and project-mcp-server-connection off the OS-internal NDJSON shim in `new-stream-runtime.ts` — consider replacing this large draft with a small task for that. - `apps/os/tasks/workspace-codemode-implementation-log.md`: Done implementation log; only marginally unique note is the rationale that plain method objects (not class instances) cross DO RPC, which is now embodied in the shipped workspace DO code. - `apps/os/tasks/migration-notes/`: Historical migration logs (not tasks) committed with and cited by merged PR #1402 one day ago; contain unique per-domain decisions plus the legacy-subscriber gap behind the 2026-06-10 prd Slack outage — maintainer should relocate to docs/ or delete deliberately. 🤖 Generated with [Claude Code](https://claude.com/claude-code)  --- > [!NOTE] > **Low Risk** > Documentation and task-file deletions only; no application runtime or API behavior changes in the diff. > > **Overview** > **Aligns OS documentation with the current worker, auth, routing, and itx reality**, and **removes a large set of completed or obsolete task files** from `apps/os/tasks/` and `tasks/`. > > The **README / AGENTS** and **`architecture-and-operations.md`** rewrites drop Clerk-era and deleted-entrypoint references (`src/app.ts`, `src/entry.workerd.ts`, `/org/:organizationSlug`) in favor of **`src/worker.ts`**, **Iterate Auth**, **project-scoped routes** (`/projects/...`, `/new-project`), **canonical MCP** (`APP_CONFIG_MCP__BASE_URL`, auth-worker OAuth), **itx** endpoints, and **`sync-auth-clients.ts`**. Deploy docs now distinguish ambient **`pnpm cf:deploy`** from production **`pnpm deploy`**. E2E docs point at **`pnpm e2e`** and **`pnpm e2e:itx`** instead of removed capnweb vitest configs. > > **Cap'n Web tombstones** in `iterate-context*.md` redirect readers to **itx** (`src/itx/`, `itx-spec.md`). Research notes get **historical** headers; **itx-spec** notes merged status on main and documents that **`connectItx` is one-shot** (no §6.3 reconnect loop). **itx README / `Stubify`** docs are corrected: typed caps use **`itx.cap("name") as Stubify<...>`**, not declaration merging. > > **CONTEXT.md** fixes the example that claimed org UI lived under `/org/...`. **headless-local-debugging** uses **`/new-project`**. > > **Task grooming** deletes many markdown tasks whose work is done, superseded (itx, auth worker), or OS1-dead — including codemode vertical-slice plans, domain oRPC refactor design, egress MVP, Slack processor unwind, and similar inventory items. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit a4f093f. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup>   ## Environment Config Lease    Lease: `preview-5` Doppler config: `preview_5` Type: `environment-config-lease` Leased until: 2026-06-10T13:19:51.555Z ### OS Status: deployed Commit: `a4f093f` Preview: https://os.iterate-preview-5.com [Workflow run](https://github.com/iterate/iterate/actions/runs/27275677688) Updated: 2026-06-10T12:23:34.040Z  --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

jonastemplestein and others added 10 commits June 9, 2026 23:06

cursor Bot reviewed Jun 10, 2026

View reviewed changes

Comment thread apps/semaphore/src/worker.ts

jonastemplestein merged commit b8d573a into main Jun 10, 2026
10 checks passed

jonastemplestein deleted the achieved-plot branch June 10, 2026 08:10

jonastemplestein mentioned this pull request Jun 10, 2026

docs(os): fix AGENTS.md, rewrite architecture-and-operations, retire capnweb pointers, fix task states #1432

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework#1411

Golden-path apps/os: TanStack Start + oRPC + Workers, no apps framework#1411
jonastemplestein merged 10 commits into
mainfrom
achieved-plot

jonastemplestein commented Jun 9, 2026 •

edited by iterate-bot

Loading

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jonastemplestein commented Jun 9, 2026 • edited by iterate-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Golden-path apps/os: TanStack Start + oRPC + Cloudflare Workers

1. The bug that started this: a sidebar link to a 404

2. Removed the "apps framework" over-abstraction

2a. app.ts (manifest + config) → config.ts; manifest deleted

2b. AppContext (hand-threaded) → RequestContext (TanStack Start's own)

2c. entry.workerd.ts (604 lines) → worker.ts (197 lines) + focused modules

3. 🔒 Security: closed an unauthenticated secret leak (rotate secrets)

4. Review & verification

5. "Wait, a simplification PR that's net +~930 lines?"

6. Update: merged main (itx) + semaphore migration

Environment Config Lease

OS

Semaphore

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jonastemplestein commented Jun 9, 2026 •

edited by iterate-bot

Loading

Golden-path `apps/os`: TanStack Start + oRPC + Cloudflare Workers

2a. `app.ts` (manifest + config) → `config.ts`; manifest deleted

2b. `AppContext` (hand-threaded) → `RequestContext` (TanStack Start's own)

2c. `entry.workerd.ts` (604 lines) → `worker.ts` (197 lines) + focused modules

6. Update: merged `main` (itx) + semaphore migration