[superche]

Summary

• make npm run codex:dev:app converge the Dev App, gateway/worker bundle, and detached local Facade as three explicit lifecycle layers
• bind Facade reuse to the exact daemon entry path and SHA-256 artifact identity instead of a manually bumped runtime version
• safely authenticate, stop, wait for, and replace only daemons owned by the current Dev runtime root while preserving credentials and runtime data
• expose independent App/cache/gateway/Facade identity, health, match, and PID transition evidence in Dev profile status
• document the lifecycle contract and add focused unit, integration, contract, and real-profile coverage

Root cause

The cold Dev profile restart stopped the App and refreshed the plugin cache, but it did not manage the detached local Facade daemon. Runtime bootstrap primarily compared PIPPIT_LOCAL_RUNTIME_VERSION, so an old daemon could be reused when code and schemas changed without a version bump. That produced a mixed generation: new Widget/MCP worker with an old Facade schema.

Design

• The ready descriptor and authenticated challenge proof now bind the absolute daemon entry, artifact SHA-256, PID, instance, port, runtime version, and start time.
• Only an exact current-bundle artifact is reusable.
• An authenticated non-exact daemon under the same runtime root receives a private shutdown request and must exit before the current bundle starts; authenticated legacy daemons use a scoped SIGTERM fallback.
• Unverified PIDs, PID reuse, other runtime roots, and stop timeouts fail closed instead of being killed broadly.
• Bootstrap locking and stale ready-file cleanup cover concurrent startup and crash recovery.
• Cold refresh replaces only process/cache state. BYOK credentials, runtime secrets, jobs, artifacts, outputs, and idempotency state are retained.

Validation

After rebasing onto the latest main:

• npm test — 53 files, 394 tests passed
• targeted lifecycle/profile tests — 31 passed
• npm run typecheck
• npm run lint
• npm run build
• npm run check:architecture
• npm run check:plugin-version
• npm run check:public-lockfile
• npm run check:plugin-contract — MCP ebd0353dbcff95babc100dfa429f69bc64639b3fd322b98c8eecba9645358112, plugin 3cb4f56273b2aa5296acfaa75f3b5e7ed8016fc273d238ddfc8e7aeb57efb5c7
• npm run check:release-artifact
• npm run check:dev-gateway — version 0.3.0, 17 tools, 2 resources, 2 templates
• git diff --check

Real isolated Dev profile evidence

Initial incident reproduction showed Dev App PID 73572 with an old 0.2.12 legacy-unidentified Facade at PID 67983; status reported matchesGateway=false. The first cold convergence replaced it and preserved runtime data.

A final cold restart after rebasing onto the latest main produced current-commit evidence:

• action: replaced
• previous Facade PID: 38427, confirmed stopped
• new Facade PID: 64465
• new App PID: 64529
• plugin version: 0.3.0
• entry: /Users/bytedance/.pippit-bridge/dev-v1/generations/bootstrap-ecc3ff1f2e08/dist/local-facade-daemon.mjs
• daemon/gateway artifact SHA-256: e8d28acb03dd4a33c300dbd312304a787163351929ad084a9ba4d6d2b936ed6c
• cache/gateway bundle SHA-256: 49543ef94345521dbb6acfe5a64f9917d6fe42c096d35ad7766ad5d94a9f1b25
• matchesExpectedArtifact=true, matchesGateway=true, healthy=true

Existing runtime secret, BYOK credential, and idempotency files remained present across the restart.

No paid upstream generation, npm publish, or production marketplace activation was performed.