@rubytech/create-sitedesk-code 0.1.524 → 0.1.525

package/payload/platform/docs/superpowers/plans/2026-06-02-task-610-follower-202-retry.md

@@ -1,372 +0,0 @@
-# Follower 202 Cold-Start Retry Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make the channel-pty-bridge JSONL follower survive the cold-spawn `202 {pending:true}` window so a fresh public webchat turn detects `end_turn` and the visitor receives the greeting instead of a 120s timeout.
-
-**Architecture:** Wrap the follower's single `fetch(/log?follow=1)` in a bounded retry loop. `202` triggers a logged retry on a poll interval until a `200` stream arrives or a give-up window elapses; `200` proceeds into the existing read/fan-out loop unchanged; other non-ok statuses keep today's `onError`+`onClose`. Two env vars (give-up window, poll interval) tune the loop, defaulting to cover claude cold-boot. The manager is untouched.
-
-**Tech Stack:** TypeScript, Node fetch + ReadableStream, vitest. Files in `maxy-code/platform/ui/app/lib/channel-pty-bridge/`.
-
----
-
-### Task 1: Extend the test fetch helper to script a follow-response sequence
-
-The current `installManagerFetch` always answers `/log?follow=1` with a `200` stream. To
-test the `202`→`200` path we need to script per-sessionId follow responses: a list of
-statuses where `202` returns the pending JSON body and `200` returns the stream.
-
-**Files:**
-- Modify: `maxy-code/platform/ui/app/lib/channel-pty-bridge/__tests__/helpers.ts`
-
-- [ ] **Step 1: Add a `followStatuses` option and apply it in the follow branch**
-
-In `ManagerFetchOptions`, add:
-
-```ts
-  /** Per-sessionId status sequence for /:id/log?follow=1. Each 202 returns
-   *  `{pending:true}` and consumes one entry; the first non-202 entry returns
-   *  the stream (200) or an error body. Cycles the last entry. When unset, the
-   *  follow branch returns 200 + stream as before. */
-  followStatuses?: Record<string, number[]>
-```
-
-In `installManagerFetch`, before the `fetchMock` definition:
-
-```ts
-  const followStatusSeq = opts.followStatuses ?? {}
-  const followStatusIdx: Record<string, number> = {}
-```
-
-Replace the existing follow branch body (the `if (followMatch && method === 'GET')` block)
-with:
-
-```ts
-    const followMatch = url.match(/\/([^/?]+)\/log\?follow=1$/)
-    if (followMatch && method === 'GET') {
-      const sessionId = followMatch[1]
-      followCalls.push(sessionId)
-      const seq = followStatusSeq[sessionId]
-      if (seq && seq.length > 0) {
-        const i = Math.min(followStatusIdx[sessionId] ?? 0, seq.length - 1)
-        followStatusIdx[sessionId] = (followStatusIdx[sessionId] ?? 0) + 1
-        const status = seq[i]
-        if (status === 202) {
-          return new Response(JSON.stringify({ jsonlPath: null, exists: false, sizeBytes: 0, pending: true }), {
-            status: 202,
-            headers: { 'content-type': 'application/json' },
-          })
-        }
-      }
-      const stream = perId[sessionId] ?? defaultFollow ?? makeJsonlStream()
-      return new Response(stream.body, {
-        status: 200,
-        headers: { 'content-type': 'application/x-ndjson' },
-      })
-    }
-```
-
-- [ ] **Step 2: Confirm the existing follower suite still compiles and passes**
-
-Run: `cd maxy-code/platform && npx vitest run ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts`
-Expected: PASS (4 tests) — the helper change is additive; `followStatuses` is unset in
-every existing test so the follow branch behaves exactly as before.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add maxy-code/platform/ui/app/lib/channel-pty-bridge/__tests__/helpers.ts
-git commit -m "test(610): scriptable follow-response sequence in manager fetch helper"
-```
-
----
-
-### Task 2: Failing test — follower retries on 202 then fans out on the 200 stream
-
-**Files:**
-- Modify: `maxy-code/platform/ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-Add inside the `describe('follower', …)` block (the `makeEntry` helper and imports already
-exist at the top of the file):
-
-```ts
-  it('retries on 202 pending then fans out once the 200 stream is available', async () => {
-    const stream = makeJsonlStream()
-    // First follow fetch → 202 pending; second → 200 + stream.
-    mgr = installManagerFetch({
-      followStream: stream,
-      followStatuses: { 'sess-aaaaaaaa': [202, 200] },
-    })
-    process.env.CHANNEL_PTY_FOLLOWER_RETRY_MS = '5'
-    process.env.CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS = '5000'
-    const entry = makeEntry()
-    const received: string[] = []
-    entry.subscribers.add((text) => {
-      received.push(text)
-    })
-    startFollower({ entry, tag: '[test]', onClose: () => {} })
-    // Wait until the retry loop has issued the second (200) follow fetch.
-    await waitFor(() => mgr.followCalls.length >= 2)
-    stream.push(
-      JSON.stringify({
-        type: 'assistant',
-        message: { content: [{ type: 'text', text: 'greeting' }], stop_reason: 'end_turn' },
-      }),
-    )
-    await waitFor(() => received.length > 0)
-    expect(received).toEqual(['greeting'])
-  })
-```
-
-Add to the `afterEach` (or a dedicated cleanup) so the env vars don't leak into other
-tests — place these two lines in the existing `afterEach` callback:
-
-```ts
-    delete process.env.CHANNEL_PTY_FOLLOWER_RETRY_MS
-    delete process.env.CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `cd maxy-code/platform && npx vitest run ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts -t "retries on 202"`
-Expected: FAIL — today the follower treats `202` as success, consumes the pending JSON
-body as a single non-event line, reads `done`, and closes. `mgr.followCalls.length` never
-reaches 2 (no retry), so `waitFor` throws "predicate never became true".
-
-- [ ] **Step 3: Commit the failing test**
-
-```bash
-git add maxy-code/platform/ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts
-git commit -m "test(610): failing test for follower 202 retry then fan-out"
-```
-
----
-
-### Task 3: Implement the bounded 202 retry loop in the follower
-
-**Files:**
-- Modify: `maxy-code/platform/ui/app/lib/channel-pty-bridge/follower.ts`
-
-- [ ] **Step 1: Add the two config readers**
-
-Below the imports (after the `type JsonlEvent = …` line, before `FollowerOptions`), add:
-
-```ts
-function followerPendingMaxMs(): number {
-  return Number(process.env.CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS ?? String(120_000))
-}
-
-function followerRetryMs(): number {
-  return Number(process.env.CHANNEL_PTY_FOLLOWER_RETRY_MS ?? String(1_000))
-}
-```
-
-- [ ] **Step 2: Replace the single-fetch guard with the retry loop**
-
-Replace this block (currently `follower.ts:42-51`):
-
-```ts
-    try {
-      const res = await fetch(managerLogFollowUrl(entry.sessionId), {
-        signal: abort.signal,
-      })
-      if (!res.ok || !res.body) {
-        opts.onError?.(`follow-status-${res.status}`)
-        opts.onClose()
-        return
-      }
-      const reader = res.body.getReader()
-```
-
-with:
-
-```ts
-    try {
-      const sid = entry.sessionId.slice(0, 8)
-      const deadline = Date.now() + followerPendingMaxMs()
-      let res: Response
-      let attempt = 0
-      for (;;) {
-        res = await fetch(managerLogFollowUrl(entry.sessionId), {
-          signal: abort.signal,
-        })
-        console.error(`${tag} follower-connect sessionId=${sid} status=${res.status}`)
-        // 202 {pending:true}: the PTY is live but claude has not flushed its
-        // first JSONL line yet (cold-spawn window). Retry on a poll interval
-        // until a 200 stream is available or the give-up window elapses.
-        if (res.status === 202) {
-          attempt += 1
-          await res.body?.cancel().catch(() => {})
-          if (abort.signal.aborted) {
-            opts.onClose()
-            return
-          }
-          if (Date.now() >= deadline) {
-            console.error(`${tag} follower-give-up sessionId=${sid} reason=pending-timeout attempts=${attempt}`)
-            opts.onError?.('follow-pending-timeout')
-            opts.onClose()
-            return
-          }
-          console.error(`${tag} follower-retry sessionId=${sid} attempt=${attempt} reason=pending`)
-          await new Promise((r) => setTimeout(r, followerRetryMs()))
-          if (abort.signal.aborted) {
-            opts.onClose()
-            return
-          }
-          continue
-        }
-        break
-      }
-      if (!res.ok || !res.body) {
-        opts.onError?.(`follow-status-${res.status}`)
-        opts.onClose()
-        return
-      }
-      console.error(`${tag} follower-open sessionId=${sid}`)
-      const reader = res.body.getReader()
-```
-
-The rest of the function (the `while (!abort.signal.aborted)` read loop, the `catch`, and
-the `finally → opts.onClose()`) is unchanged. `onClose` still fires exactly once on every
-exit path: each early `return` inside the loop calls `onClose()` directly and returns
-before the read loop; the normal stream-end / abort / error paths fall through to the
-existing `finally`.
-
-- [ ] **Step 3: Run the new test to verify it passes**
-
-Run: `cd maxy-code/platform && npx vitest run ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts -t "retries on 202"`
-Expected: PASS — first fetch returns 202, follower logs `follower-retry`, second fetch
-returns the 200 stream, `follower-open` logs, the `end_turn` record fans out `'greeting'`.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add maxy-code/platform/ui/app/lib/channel-pty-bridge/follower.ts
-git commit -m "fix(610): follower retries on 202 cold-start, never silently closes"
-```
-
----
-
-### Task 4: Give-up test — persistent 202 ends with onError + onClose, no fan-out
-
-**Files:**
-- Modify: `maxy-code/platform/ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts`
-
-- [ ] **Step 1: Write the test**
-
-Add inside the `describe` block:
-
-```ts
-  it('gives up after the pending window: onError + onClose, no fan-out', async () => {
-    const stream = makeJsonlStream()
-    // Every follow fetch returns 202 — the JSONL never appears.
-    mgr = installManagerFetch({
-      followStream: stream,
-      followStatuses: { 'sess-aaaaaaaa': [202] },
-    })
-    process.env.CHANNEL_PTY_FOLLOWER_RETRY_MS = '2'
-    process.env.CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS = '20'
-    const entry = makeEntry()
-    const received: string[] = []
-    entry.subscribers.add((text) => {
-      received.push(text)
-    })
-    const onError = vi.fn()
-    const onClose = vi.fn()
-    startFollower({ entry, tag: '[test]', onError, onClose })
-    await waitFor(() => onClose.mock.calls.length > 0)
-    expect(onError).toHaveBeenCalledWith('follow-pending-timeout')
-    expect(onClose).toHaveBeenCalledTimes(1)
-    expect(received).toEqual([])
-  })
-```
-
-- [ ] **Step 2: Run it**
-
-Run: `cd maxy-code/platform && npx vitest run ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts -t "gives up"`
-Expected: PASS — repeated 202s exceed the 20ms window, follower logs `follower-give-up`,
-calls `onError('follow-pending-timeout')` and `onClose()` once, no text delivered.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add maxy-code/platform/ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts
-git commit -m "test(610): follower gives up after pending window"
-```
-
----
-
-### Task 5: Full suite + typecheck + lint
-
-**Files:** none (verification only)
-
-- [ ] **Step 1: Run the whole channel-pty-bridge suite**
-
-Run: `cd maxy-code/platform && npx vitest run ui/app/lib/channel-pty-bridge/__tests__/`
-Expected: PASS — all follower tests (6 now), plus dispatch-once, reaper, subscribe,
-write-chain, public-session-exit, live-memory-eviction, spawn-refused.
-
-- [ ] **Step 2: Typecheck the changed files**
-
-Run: `cd maxy-code/platform && npx tsc --noEmit -p ui/tsconfig.json 2>&1 | grep -E 'follower|helpers' || echo "no type errors in changed files"`
-Expected: `no type errors in changed files`.
-
-- [ ] **Step 3: Lint the changed files**
-
-Run: `cd maxy-code/platform && npx eslint ui/app/lib/channel-pty-bridge/follower.ts ui/app/lib/channel-pty-bridge/__tests__/follower.test.ts ui/app/lib/channel-pty-bridge/__tests__/helpers.ts`
-Expected: no errors.
-
----
-
-### Task 6: Documentation — webchat turn lifecycle + new env vars
-
-**Files:**
-- Modify or create: the webchat turn lifecycle reference under `maxy-code/platform/plugins/docs/references/` and the matching internal note under `maxy-code/.docs/` (locate the existing channel-pty-bridge / webchat doc first with a grep; edit it rather than creating a duplicate).
-
-- [ ] **Step 1: Locate the existing doc**
-
-Run: `cd maxy-code && grep -rln "channel-pty-bridge\|dispatchOnce\|log-follow-open\|WEBCHAT_TURN_TIMEOUT" .docs/ platform/plugins/docs/references/ 2>/dev/null`
-Edit the file(s) that own the webchat turn lifecycle. If none exists, add a short
-"Webchat turn lifecycle" section to the most relevant existing reference.
-
-- [ ] **Step 2: Document the cold-start retry and env vars**
-
-Add prose covering: the follower opens `GET /:sessionId/log?follow=1`; a cold spawn
-returns `202 {pending:true}` until claude flushes its first JSONL line; the follower
-retries every `CHANNEL_PTY_FOLLOWER_RETRY_MS` (default 1000) until a 200 stream arrives or
-`CHANNEL_PTY_FOLLOWER_PENDING_MAX_MS` (default 120000) elapses, then gives up with
-`follower-give-up`. Note the log signature for diagnosis: `follower-connect` →
-`follower-retry`* → `follower-open` → `outbound`, mirroring the manager's `log-follow-open`.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add maxy-code/.docs maxy-code/platform/plugins/docs/references
-git commit -m "docs(610): webchat follower cold-start retry + env vars"
-```
-
----
-
-## Self-Review
-
-**Spec coverage:**
-- Follower retries on 202 → Task 3. ✓
-- Env-tunable bound (give-up window + poll interval) → Task 3 Step 1, defaults 120000 / 1000. ✓
-- Repro test (202→200, fan-out) → Task 2. ✓
-- Give-up test → Task 4. ✓
-- Warm-session regression (existing 4 tests unchanged) → Task 1 Step 2, Task 5 Step 1. ✓
-- Observability log points (follower-connect / follower-retry / follower-open / follower-give-up) → Task 3 Step 2. ✓
-- Manager untouched → no task modifies http-server.ts. ✓
-- Docs → Task 6. ✓
-- No behaviour change for other channels → no channel-specific code added; covered by shared-follower note in spec. ✓
-
-**Placeholder scan:** Task 6 requires a grep-locate because the doc's exact path is not yet
-known; the content to write is fully specified, only the target file is discovered at
-execution. Acceptable — it is not a content placeholder.
-
-**Type consistency:** `followerPendingMaxMs()` / `followerRetryMs()` used consistently;
-`followStatuses` option name matches between helper definition (Task 1) and test use
-(Tasks 2, 4); `follow-pending-timeout` error string matches between Task 3 and Task 4
-assertion.

package/payload/platform/docs/superpowers/plans/2026-06-04-public-agent-knowledge-delivery.md

@@ -1,230 +0,0 @@
-# Public Agent Knowledge Delivery — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make the public agent's `KNOWLEDGE.md` reach its spawn prompt, refuse a dud (empty/missing SOUL or KNOWLEDGE) public spawn with a distinct logged reason, and stop seeding/reading the dead public `SOUL`/`config` templates and `plugins` config field.
-
-**Architecture:** The only spawn-prompt path is `composeAppendSystemPrompt` in `claude-session-manager`. It reads `agents/<role>/{IDENTITY,SOUL}.md`; we add a public-only `KNOWLEDGE.md` read rendered as `<knowledge>` after `<soul>`, with strict empty/missing refusal. `pty-spawner` maps the new refusal reasons and emits the per-spawn byte-count line. The installer stops manufacturing a public agent on fresh install but re-syncs the Rubytech IDENTITY into existing agent dirs on upgrade. The UI config reader drops the unused `plugins` field. The admin skill doc is corrected to match.
-
-**Tech Stack:** TypeScript (Node, vitest), bash (`setup-account.sh`), markdown (SKILL.md).
-
----
-
-### Task 1: `system-prompt.ts` — read KNOWLEDGE for public, distinct refusal reasons
-
-**Files:**
-- Modify: `services/claude-session-manager/src/system-prompt.ts`
-- Test: `services/claude-session-manager/src/__tests__/system-prompt.test.ts`
-
-**Behaviours:**
-- `AppendBlockResult` ok:true gains `knowledgeBytes: number`.
-- `AppendBlockResult` ok:false `reason` union gains `'soul-empty' | 'knowledge-missing' | 'knowledge-empty'`.
-- `renderAppendBlock` gains a `knowledgeContent: string | null` param; when non-null, render `<knowledge>\n{content}\n</knowledge>` immediately after `</soul>`, before `<about-owner>`; return `knowledgeBytes`. Null ⇒ no block, no bytes (admin + self-test + drift unchanged).
-- `composeAppendSystemPrompt`: IDENTITY failure → `identity-unresolved` (all roles, unchanged). SOUL failure → `identity-unresolved` for admin (unchanged); for `role==='public'` → `soul-empty`. When `role==='public'`, read `<roleDir>/KNOWLEDGE.md` via `readIdentityFile`: detail ending `:empty` → `knowledge-empty`; any other failure (ENOENT/unreadable) → `knowledge-missing`. Pass content to `renderAppendBlock`; admin passes `null`.
-
-- [ ] **Step 1: Write failing tests** — append to `system-prompt.test.ts`:
-
-```ts
-describe('composeAppendSystemPrompt — public KNOWLEDGE delivery', () => {
-  function makePublic(seed: { identity?: string | null; soul?: string | null; knowledge?: string | null }): string {
-    const dir = mkdtempSync(join(tmpdir(), 'task618-account-'))
-    const roleDir = join(dir, 'agents', 'public')
-    mkdirSync(roleDir, { recursive: true })
-    if (typeof seed.identity === 'string') writeFileSync(join(roleDir, 'IDENTITY.md'), seed.identity)
-    if (typeof seed.soul === 'string') writeFileSync(join(roleDir, 'SOUL.md'), seed.soul)
-    if (typeof seed.knowledge === 'string') writeFileSync(join(roleDir, 'KNOWLEDGE.md'), seed.knowledge)
-    return dir
-  }
-
-  it('public + non-empty KNOWLEDGE ⇒ <knowledge> verbatim, ordered after <soul>, knowledgeBytes>0', () => {
-    const knowledge = '# Knowledge\nWe open 9-5. Sale price £450k.\n'
-    const accountDir = makePublic({ identity: 'I', soul: 'S', knowledge })
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
-      expect(result.ok).toBe(true)
-      if (!result.ok) return
-      expect(result.block).toContain(`<knowledge>\n${knowledge}\n</knowledge>`)
-      expect(result.block.indexOf('<knowledge>')).toBeGreaterThan(result.block.indexOf('</soul>'))
-      expect(result.knowledgeBytes).toBe(Buffer.byteLength(knowledge, 'utf8'))
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-
-  it('public + missing KNOWLEDGE ⇒ ok:false reason=knowledge-missing', () => {
-    const accountDir = makePublic({ identity: 'I', soul: 'S' })
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
-      expect(result.ok).toBe(false)
-      if (result.ok) return
-      expect(result.reason).toBe('knowledge-missing')
-      expect(result.detail).toContain('KNOWLEDGE.md')
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-
-  it('public + empty KNOWLEDGE ⇒ ok:false reason=knowledge-empty', () => {
-    const accountDir = makePublic({ identity: 'I', soul: 'S', knowledge: '' })
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
-      expect(result.ok).toBe(false)
-      if (result.ok) return
-      expect(result.reason).toBe('knowledge-empty')
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-
-  it('public + empty SOUL ⇒ ok:false reason=soul-empty', () => {
-    const accountDir = makePublic({ identity: 'I', soul: '', knowledge: 'K' })
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
-      expect(result.ok).toBe(false)
-      if (result.ok) return
-      expect(result.reason).toBe('soul-empty')
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-
-  it('public + empty IDENTITY ⇒ identity-unresolved (unchanged)', () => {
-    const accountDir = makePublic({ identity: '', soul: 'S', knowledge: 'K' })
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
-      expect(result.ok).toBe(false)
-      if (result.ok) return
-      expect(result.reason).toBe('identity-unresolved')
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-
-  it('admin + KNOWLEDGE.md on disk ⇒ no <knowledge> block', () => {
-    const accountDir = makeAccountDir({ admin: { identity: 'I', soul: 'S' } })
-    writeFileSync(join(accountDir, 'agents', 'admin', 'KNOWLEDGE.md'), 'admin-knowledge')
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'admin' })
-      expect(result.ok).toBe(true)
-      if (!result.ok) return
-      expect(result.block).not.toContain('<knowledge>')
-      expect(result.block).not.toContain('admin-knowledge')
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-
-  it('snapshot: full composed public prompt with a sample KNOWLEDGE.md', () => {
-    const accountDir = makePublic({
-      identity: '# Identity\nYou speak for the business.',
-      soul: '# Soul\nWarm, brief.',
-      knowledge: '# Knowledge\nOpen 9-5. Contact 01234 567890.',
-    })
-    try {
-      const result = composeAppendSystemPrompt(HOST, { accountDir, role: 'public' })
-      expect(result.ok).toBe(true)
-      if (!result.ok) return
-      expect(result.block).toMatchSnapshot()
-    } finally { rmSync(accountDir, { recursive: true, force: true }) }
-  })
-})
-```
-
-- [ ] **Step 2: Run, verify fail** — `npx vitest run src/__tests__/system-prompt.test.ts` → FAIL (knowledge not read).
-
-- [ ] **Step 3: Implement** in `system-prompt.ts`:
-  - Add `knowledgeBytes: number` to ok:true; extend ok:false reason union.
-  - Add `knowledgeContent: string | null` param to `renderAppendBlock`; insert `<knowledge>` block after `</soul>` push, before `<about-owner>`; track + return `knowledgeBytes`.
-  - Update both internal `renderAppendBlock` callers (`runIdentityDriftAssertion`, `runSystemPromptSelfTest`) to pass `null`.
-  - In `composeAppendSystemPrompt`: on SOUL failure, `return { ok:false, reason: sources.role === 'public' ? 'soul-empty' : 'identity-unresolved', detail: soul.detail }`. When `role==='public'`, read `KNOWLEDGE.md`; on failure `return { ok:false, reason: knowledge.detail.endsWith(':empty') ? 'knowledge-empty' : 'knowledge-missing', detail: knowledge.detail }`. Pass `role==='public' ? knowledge.content : null` to `renderAppendBlock`; set `knowledgeBytes` accordingly (0 for admin).
-
-- [ ] **Step 4: Run, verify pass** — `npx vitest run src/__tests__/system-prompt.test.ts` → PASS. Review the new snapshot.
-
-- [ ] **Step 5: Commit** — `feat(public-agent): read KNOWLEDGE.md into public spawn prompt with strict refusal`
-
----
-
-### Task 2: `pty-spawner.ts` — surface refusal reasons + per-spawn compose line
-
-**Files:**
-- Modify: `services/claude-session-manager/src/pty-spawner.ts` (`SpawnFailureReason` ~351; compose handling ~1292-1315)
-
-**Behaviours:**
-- `SpawnFailureReason` gains `'soul-empty' | 'knowledge-missing' | 'knowledge-empty'`.
-- In the `!composed.ok` branch, for the three new reasons emit `[pty-spawn] spawn-failed reason=<r> role=public slug=<agentSlug>` and return `{ ok:false, reason:<r>, stderrTail: composed.detail }`. The existing `identity-unresolved` path is unchanged.
-- Track `knowledge` in `composedBytes`. On public success emit `[pty-spawn] op=public-prompt-compose role=public slug=<agentSlug> identityBytes=N soulBytes=N knowledgeBytes=N` (in addition to the existing `compose-system-prompt-ok` line, which gains `knowledgeBytes`).
-
-- [ ] **Step 1: Implement** — extend the union; in the failure branch add a `case` for the three reasons before the identity fallthrough; add `knowledge: composed.knowledgeBytes` to `composedBytes`; append `knowledgeBytes=${composed.knowledgeBytes}` to the `compose-system-prompt-ok` log; after that log, `if (args.role === 'public') deps.logger(\`op=public-prompt-compose role=public slug=${agentSlug} identityBytes=${composed.identityBytes} soulBytes=${composed.soulBytes} knowledgeBytes=${composed.knowledgeBytes}\`)`.
-
-- [ ] **Step 2: Verify** — `npx vitest run` for csm (no test directly asserts these strings; the build + existing suite must stay green). Confirm tsc has no error on the union/result fields.
-
-- [ ] **Step 3: Commit** — `feat(public-agent): map knowledge/soul refusal reasons + emit public-prompt-compose line`
-
----
-
-### Task 3: Templates — delete dead public SOUL + config
-
-**Files:**
-- Delete: `templates/agents/public/SOUL.md`, `templates/agents/public/config.json`
-- Keep: `templates/agents/public/IDENTITY.md`
-
-- [ ] **Step 1:** `git rm templates/agents/public/SOUL.md templates/agents/public/config.json`
-- [ ] **Step 2: Verify no live reader** — `grep -rIn 'agents/public/SOUL\|agents/public/config' --include=*.ts --include=*.sh .` returns only `setup-account.sh` lines removed in Task 4. (`smoke-boot-services.sh` and `verify-doc-impl.sh` copy/grep IDENTITY only.)
-- [ ] **Step 3: Commit** with Task 4 (template deletion is meaningless without the seed removal).
-
----
-
-### Task 4: `setup-account.sh` — no fresh-install public agent; re-sync IDENTITY for existing
-
-**Files:**
-- Modify: `scripts/setup-account.sh` (mkdir ~38; IDENTITY block ~181-184; SOUL/config seed ~221-224)
-
-**Behaviours:**
-- Drop `"$ACCOUNT_DIR/agents/public"` from the line-38 `mkdir -p`.
-- Remove the public IDENTITY overwrite (lines 183-184) and the public SOUL/config seed (lines 221-224).
-- Add, in the agent-identities section, a loop: for each `"$ACCOUNT_DIR/agents"/*/` whose basename ≠ `admin` and which already contains `IDENTITY.md`, overwrite `IDENTITY.md` from `"$TEMPLATES_DIR/agents/public/IDENTITY.md"`; echo a re-sync line. Never create dirs; never write SOUL/KNOWLEDGE/config. Admin block untouched.
-
-- [ ] **Step 1: Implement** the three edits.
-- [ ] **Step 2: Verify fresh install** — run `setup-account.sh` against a scratch `ACCOUNT_DIR` with no `agents/public`; assert no `agents/public/` is created and `agents/admin/IDENTITY.md` exists.
-- [ ] **Step 3: Verify upgrade** — scratch `ACCOUNT_DIR` pre-seeded with `agents/sales/IDENTITY.md` (stale text) + `agents/sales/SOUL.md`; run; assert `agents/sales/IDENTITY.md` now equals the template and `agents/sales/SOUL.md` is untouched.
-- [ ] **Step 4: Commit** (with Task 3) — `refactor(installer): public agents author client-side; re-sync IDENTITY for existing dirs only`
-
----
-
-### Task 5: `account.ts` — drop the dead `plugins` config field
-
-**Files:**
-- Modify: `ui/app/lib/claude-agent/account.ts` (`ResolvedAgentConfig` ~277; reader ~304,324; return ~395)
-- Test: `ui/app/lib/claude-agent/__tests__/spawn-context.test.ts` (trim `plugins` assertions only)
-
-**Behaviours:**
-- Remove `plugins: string[] | null` from `ResolvedAgentConfig`; remove `let plugins`, the `parsed.plugins` read, and `plugins` from the return object. Leave `knowledgeKeywords` and the budget-breakdown `plugins: 0` token field intact.
-
-- [ ] **Step 1: Find & update the test** — `grep -n 'plugins' ui/app/lib/claude-agent/__tests__/spawn-context.test.ts`; remove only the assertions reading `config.plugins`; add/confirm a case that a public `config.json` lacking `plugins` resolves and `knowledgeKeywords` is still read.
-- [ ] **Step 2: Run, verify fail/observe** — `npx vitest run ui/app/lib/claude-agent/__tests__/spawn-context.test.ts`.
-- [ ] **Step 3: Implement** the field removal in `account.ts`.
-- [ ] **Step 4: Run, verify pass** — same vitest command → PASS.
-- [ ] **Step 5: Commit** — `refactor(public-agent): drop unused plugins field from resolved agent config`
-
----
-
-### Task 6: `public-agent-manager/SKILL.md` — correct the doc
-
-**Files:**
-- Modify: `plugins/admin/skills/public-agent-manager/SKILL.md`
-
-**Behaviours (scope item 6):**
-- (a) Table: `KNOWLEDGE.md` Required → Yes; `SOUL.md` purpose → personality + role (basic public info, capture the visitor's contact details for human follow-up — the chat equivalent of the landing-page contact form). Add a line: SOUL.md and KNOWLEDGE.md are authored entirely client-side and must be non-empty before the agent goes active; an empty one is refused at spawn. KNOWLEDGE = the business's public-facing facts at landing-page detail.
-- (b) Create step: IDENTITY.md is copied from the Rubytech template verbatim, not drafted/edited.
-- (c) Remove the `plugins` key from the `config.json` example; remove "selected plugins" from the table; delete the "Plugin Selection" section; remove the plugin-selection Create step and renumber the Create steps + every cross-reference (`Step 4/5/6/7`, `All other steps (4, 8-12)`). Update the template-create plugin pre-select bullet (plugins gone) and note IDENTITY is the fixed Rubytech template.
-- (d) Ensure no reference to a SOUL/config seed template remains.
-- Keep: `knowledgeKeywords` field, the create-form field, keyword-subscription and direct-tagging sections, projection steps.
-
-- [ ] **Step 1: Implement** the edits above.
-- [ ] **Step 2: Verify** — `grep -n 'plugins' SKILL.md` shows no `plugins` config key or Plugin Selection section (knowledgeKeywords/tagging prose may remain); Create steps are sequentially numbered with consistent cross-refs.
-- [ ] **Step 3: Commit** — `docs(public-agent): KNOWLEDGE required, IDENTITY templated, drop plugins from skill`
-
----
-
-### Task 7: Verify — build, bundle, full suites
-
-- [ ] **Step 1:** `npm run build:claude-session-manager` → no tsc errors.
-- [ ] **Step 2:** Full csm suite `cd services/claude-session-manager && npx vitest run` → green (esp. `public-identity-template`, `pty-spawner-channels`).
-- [ ] **Step 3:** `npx vitest run ui/app/lib/claude-agent/__tests__/` → green.
-- [ ] **Step 4:** Bundle the installer payload (`maxy-code/packages/create-maxy-code` `npm run bundle`) → no runtime errors; confirm `templates/agents/public/` in the payload contains only `IDENTITY.md`.
-
----
-
-## Self-Review
-
-- **Spec coverage:** scope 1→T1, 2→T2, 3→T3, 4→T4, 5→T5, 6→T6; verification + observability→T1/T2/T7. All covered.
-- **Out of scope (untouched):** `knowledgeKeywords` machinery, projection routes, the migrated Real Agent agent's KNOWLEDGE authoring, Pi hand-patched files.
-- **Type consistency:** `knowledgeBytes` and the three reasons named identically in T1 (composer) and T2 (spawner). `renderAppendBlock` `knowledgeContent` param threaded through all three callers.