e10-ebuilder-prototype 0.5.5 → 0.5.7

package/docs/PROTOCOL.md

@@ -1,4 +1,4 @@
-# Contract v10 — e10-ebuilder-prototype 0.5.5
+# Contract v14 — e10-ebuilder-prototype 0.5.7
 
 Product, npm package, CLI and Skill share this name. Node >=22.5, TypeScript/ESM,
 pinned playwright-core and installed Chrome. No LLM calls in CLI: host AI generates
@@ -37,11 +37,25 @@ parentKey-childMenuId); objId, underlying formId and listId are not interchangea
 ## Commands and state
 
 Commands: init, next, discover, collect, capture, run, retry, status, pack, doctor;
-html next|inspect|ready|accept|fail|retry; auth set|status|profile list|current|use NAME.
+html next|watch|inspect|interact|ready|accept|fail|retry; auth set|status|profile list|current|use NAME.
 Auth set supports --base-url, --eteamsid-stdin and --eteamsid. JSON returns one final
 object; progress uses stderr. Normal operations expose next, errors expose fix.
 Exit 0 = normal/DONE, 2 = PARTIAL, 1 = blocking error.
 
+The user obtains and supplies ETEAMSID; the tool only validates, encrypts/stores and
+injects that supplied session into owned browser contexts and source requests. A newly
+supplied value is imported directly without asking again. Missing/invalid/expired
+authentication without a replacement stops source work and asks the user for a new
+ETEAMSID for the target environment. The host ends the turn and waits for that input;
+it must not retry with the old credential, request/use account passwords, invoke login
+bridge Skills, or open a browser to obtain a new session/extract cookies. Auth set validates the new
+user-supplied value via stdin before saving it; failed validation returns to the same
+waiting boundary. Resume in the original directory, using sourceRecovery for failed
+sources. Never echo credentials. Missing local auth, WAITING_AUTH reports and
+E10_LOGIN_REQUIRED errors include this recovery instruction in fix. auth status --local
+only checks stored configuration; it does not prove live server authentication. Offline
+HTML generation and packaging retain their existing auth-free behavior.
+
 Reports include effectiveSettings and, for failed sources, an executable sourceRecovery
 descriptor with failure stage/attempt duration. run/capture resume pending work only;
 retry explicitly retries failed sources. Resume flags must match persisted settings,
@@ -123,9 +137,32 @@ chains are interpreted by host AI as local mock behavior, not executed on the se
 Reference failures become explicit warnings; primary metadata failures fail collection;
 auth loss always aborts the phase, retaining interrupted receipts for resume.
 
+Host collection reports count each form warning category by distinct menu ID from current
+CLI output/private inputs, preserving different menus on the same object. Screenshot
+warnings count page IDs instead; page counts cannot be presented as menu counts. Counts and
+affected identity lists must agree; names label those IDs, including duplicate names.
+Truncated output or prior prose is not a counting source.
+Distinguish core collection success, layout/mode-button reference availability, screenshot
+success, generated HTML and packaging. Review both formWarnings and warnedPages; selected
+highlights cannot be presented as an exhaustive warning inventory. A shared deployment
+probe warning repeated across menus is not evidence of repeated requests, lost configs,
+or a particular HTTP/auth/network cause. no-accessible-record does not prove an empty
+database or export failure; an absent temporary-record option is not a diagnosed cause.
+State actual fallback impacts, preserve empty versus unavailable button scopes, and
+disclose other observed gaps such as first-level-only choices and page resource errors.
+Nonblocking reference fallbacks continue without an unsolicited authorization/pause step.
+User-requested temporary-reference recollection must honor existing authorization, the
+new-directory rule for an already collected read-only task, and uncertain cleanup gates;
+never promise in-place source replacement or guaranteed reference retrieval. Skill ships
+positive/negative reporting examples; these are guidance, not new collector capabilities
+or proof of host-model compliance.
+
 ## Page capture
 
-Capture defaults: concurrency 6 (1..8 override), PC 1440x900, mobile 390x844,
+CLI defaults: concurrency 6 (1..8 override); the WorkBuddy Skill explicitly passes
+--concurrency 8 on new run/init tasks unless the user specifies another value. Existing
+tasks retain persisted settings; never append the new default to resume commands.
+Capture viewport defaults: PC 1440x900, mobile 390x844,
 CSS pixel scale 1, initial navigation/rendering deadline 10 seconds, 1 additional retry for non-timeout errors; timeouts fail immediately, stabilization
 window 800ms, page height limit 50000px, pixel limit 60M. No timeout is treated as ready.
 Readiness uses either page entrance/configuration or meaningful content bound to the requested
@@ -170,32 +207,95 @@ resource cleanup and optional diagnostics are outside the loading deadline.
 html next is a short locked transaction after all source jobs are terminal. It returns
 up to settings.concurrency jobs total (default 6), including resumed running tokens.
 Each job has kind, pageId, token, name, outputPath, reviewDirectory and prompt.
-New jobs use prompt version 12. Page jobs use screenshotPath and PNG digest. Form jobs use sourcePath,
-runtimePath and form-input digest, plus contextPath (bounded lossless
+New jobs use prompt version 17. Page jobs use screenshotPath and PNG digest. Form jobs use sourcePath,
+runtimePath and form-input digest, plus generationPath (digest-verified generation view) and contextPath (bounded lossless
 configuration fragments, grouped into bounded entries arrays and reused by verified digest; schema 4 limits each file to 18K characters and each encoded line to 1800 characters), guidePath (compact common rules plus only the current menu kind), referenceGuidePath (full manual, optional targeted lookup), navigationPath (published
 route mapping), and relatedPath (verified objects and metadata fragment paths for explicit relations). Form pageId is the menu key.
+Generation view schema 1 retains every option-extracted configuration property, including
+unknown fields, conditions, full action chains, mode differences and empty/unavailable
+statuses. JSON Pointer references reuse exact subtrees; bases use shallow set overrides and
+explicit removed keys, with literal escaping. Before writing, expansion must deeply equal
+the input with only reference HTML replaced by a structural view. Original schema-4 source
+fragments remain available for targeted fallback. Generation fragments are <=18K characters
+and <=1800 encoded characters per line. The directory identifies field groups, relations
+and configuration sections; it is not a replacement for reading all current-menu fragments.
+Related metadata is read only for explicit references; all required target fields still seed
+shared storage. Runtime examples supplement the compact guide, never authorize buttons.
+
+parse5 extracts reference-HTML parent/order, field IDs and main/detail bindings, known static
+labels, layout classes and selected inline layout/visibility styles without record text,
+scripts or resources. Visibility hints are lexical clues, not computed CSS or permission
+proof. Ambiguous bindings, unknown headings/widgets and absent field evidence retain original
+character offsets for targeted fallback. Full raw HTML remains private and is never executed.
+The generation view is not an independent form renderer; host AI still interprets business
+configuration and composes HTML. The fixed basic executor below owns its supported transactions. Smaller input is not proof of generation speed or functional fidelity.
+
 The coordinator tracks live tokens and serializes queue mutations; workers generate
-HTML and call only their token-scoped html inspect/ready for local visual QA. Jobs include an
+HTML and call only their token-scoped html inspect/interact/ready for local visual QA. Jobs include an
 inspection command/args descriptor; full images stay in the corresponding worker context.
 The coordinator reads the receipt and concise findings before acceptance. Host parallel capability governs actual AI parallelism;
-when unavailable, process sequentially and report honestly. No model subprocess/API. WorkBuddy passes the current coordinator model explicitly to each native
-background Agent, without overriding inheritable reasoning settings. inherit/default alone
-is not sufficient because WorkBuddy resolves built-in subagent defaults first. Never pin a
-specific model in this product. If equivalent configuration cannot be established, use the
-main task sequentially and disclose the reason. Receive each completed job independently
+other hosts may process sequentially when unavailable, but WorkBuddy must pause until its
+agent-team prerequisite passes. No model subprocess/API. Worker models follow explicit
+user selection or host configuration; they need not match the coordinator. When the user
+has not selected a worker model, the native Agent call may omit model and use host defaults.
+No coordinator-model lookup or model-matching pause is required. html next no longer emits
+host.modelPolicy or host.modelArgument. A coordinator model change does not cancel healthy
+workers; replacement of any writer still requires confirmed termination. Quota exhaustion
+retains the existing stop-and-report behavior; no model pool or automatic rotation is added.
+Receive each completed job independently
 and refill immediately, without waiting for a whole foreground batch. When idle, yield the
 host turn and resume on native inbox notifications; do not loop wait/sleep/TaskOutput, which
 triggers WorkBuddy loop protection. A yielded turn does not mean the application is complete.
 
 bootstrap status, doctor and html next expose host.background from inherited host flags:
-enabled/disabled/unknown. A disabled team/background flag takes precedence. This is a
-preflight signal, not proof of live workers: verify immediate native task-ID return and
-independent completion. Desktop WorkBuddy defaults disableAgentTeams to true; use its
-supported settings UI and refresh the host process. Never change host safety settings
-or export a child-shell variable and claim that it configured the parent coordinator.
+enabled/disabled/unknown. Also expose normalized agentTeams (enabled/disabled/unknown),
+backgroundTasks (allowed/disabled/unknown), evidenceSource=inherited-host-environment and
+evidenceScope=current-session. These describe inherited session flags, not UI settings
+or an API query of current preferences; never echo raw environment values. A disabled
+team/background flag takes precedence. WorkBuddy
+requires enabled before installation, auth mutation, task creation, source work, generation
+or packaging. bootstrap status keeps ready for runtime installation and adds taskReady;
+blocked status/ensure/run return exit 1 and one stdout JSON with blocked=true,
+state=WAITING_HOST, error.code=HOST_BACKGROUND_DISABLED or HOST_BACKGROUND_UNVERIFIED,
+userMessage, fix, next=enable-agent-teams and host. WAITING_HOST is a command-level
+prerequisite result, not a persisted task-state transition. No install lock, task/token
+mutation or source request occurs. Already-installed runtimes still enforce the gate.
+The wrapper requires enabled even when flags are absent. Direct CLI mutations apply the
+same gate when either WorkBuddy capability flag is present; ordinary other-host CLI use
+without those flags retains its existing behavior. Help/version, doctor, task status/next,
+auth status/profile list/current and html watch remain available for diagnosis.
+
+WorkBuddy must show userMessage verbatim in its user-visible reply and end the turn,
+not merely leave it in tool output or offer serial fallback. The message explains that
+application prototypes require concurrent page generation/review; serial processing would
+make the overall task take much longer, so agent teams are required before continuing.
+Do not invent a duration estimate or guaranteed speedup. It directs the user to
+avatar → 设置 → 智能体 → 智能体团队管理: click 取消禁用 when shown; 禁用 means already
+enabled and must not be clicked. Fully restart WorkBuddy, return to the same task and
+reply 继续. Recheck status after that response before resuming with existing artifacts;
+the user's statement alone is not a passing check. Unknown means unverified, not disabled.
+For a disabled team flag, say the current session reports teams have not taken effect;
+for an explicit background-disable flag, say this session reports background tasks
+unavailable, even when its team flag is enabled. Do not tell the user that their UI
+setting is off. If the UI is enabled but restart still leaves the session blocked,
+explain a possible host settings/session mismatch and direct a WorkBuddy issue report
+instead of repeating the same toggle/restart loop. Preferences alone cannot override
+a disabled session flag. The CLI does not inspect or modify private host configuration.
+Never alter host settings, forge flags or use a child-shell export to bypass this check.
+The CLI owns deterministic gating/copy; the host owns rendering the message to the user.
+
+Enabled is a preflight signal, not proof of live workers: the first actual native Agent
+must return a background task ID immediately and later deliver independent completion.
+If it returns synchronously or reports teams disabled, stop new dispatch and show the
+same recovery instructions; no separate probe Agent or serial fallback. Preserve existing
+worker identities and confirm execution termination before any later replacement.
 
 html next --brief writes each full prompt to the token-owned promptPath and omits prompt
-text from the response; workers read their own prompt. Output includes allocatedAt, elapsedMs,
+text from the response; workers read their own prompt. With durable registration or legacy host-active-tokens,
+already dispatched jobs return only kind/pageId/token/name/resumed and do not regenerate
+prompts or configuration views. Dispatchable jobs retain full descriptions and promptPath.
+Without a host token snapshot, brief retains its previous description shape.
+Full descriptions include allocatedAt, elapsedMs,
 hasDraft and host scheduling guidance. These describe reservations, not evidence of live AI.
 html accept|fail --refill [--brief] returns nextHtml in the same locked transaction, avoiding
 an extra host round trip. The completed receipt is committed before refill and remains valid
@@ -204,6 +304,17 @@ failure permits one recovery after the old writer exits; persistent failures rel
 with html fail. Host guidance reports no progress at 3 minutes and requests cancellation at
 5 minutes; retry requires confirmed termination, never elapsed time alone.
 
+`html inspect` records distinct rendered source revisions in the token's private
+review-history.json. Both viewports, unchanged cache reuse and damaged-image repairs share
+a revision. The standard budget is the first version plus two correction versions. Further
+new versions require --repair-reason (1..500 characters), explaining a concrete missing
+module, business or runtime error; the reason is durable. This enforces explicit exceptions,
+not the truth of a host's reason. It never auto-accepts, weakens ready checks, locks the whole
+queue or limits another token. Corrupt history fails explicitly; never delete it to reset a
+budget. Workers use one applicable primary interaction path plus fixes' affected paths;
+no ad-hoc VM/stub-DOM frameworks, tool exploration or cosmetic measurement loops. Actual
+untested interactions are recorded as untested, not silently dropped from implementation.
+
 `html ready --kind KIND --page-id ID --token TOKEN --summary TEXT` records the worker's
 explicit visual-review handoff privately. It requires current successful inspections and
 intact screenshots (page source width; forms 1440 and 390), and a nonempty <=4000-character
@@ -218,20 +329,59 @@ from stranding completed jobs. Host notes remain attestations, not independent v
 interaction proof. Native notifications wake the coordinator; they are not the source of
 truth for reviewed artifact completion. The CLI still contains no model calls.
 
-WorkBuddy coordinators pass `--host-active-tokens '["TOKEN", ...]'` on every html next
-and accept/fail --refill. The array includes every dispatched worker without a confirmed
-native terminal event, including workers whose HTML has already been accepted. First use
-passes [] only when no workers exist. Invalid/duplicate tokens fail before queue mutation.
-Allocation counts the union of running CLI tokens and these active native tokens against
-settings.concurrency; ready/accept alone cannot create a seventh slot. Returned
-host.dispatchTokens limits which reserved jobs may actually start, excluding active workers
-and respecting native free capacity. The coordinator registers every spawn immediately,
-handles duplicate/late terminal events idempotently by task_id and retains unknown states.
-If no jobs remain but native workers do, next=host-wait; do not package until they exit.
-The host supplies lifecycle evidence; the CLI does not inspect private host logs or claim
-independent liveness verification. Omission retains legacy CLI allocation behavior for
-other hosts, but is not permitted by the WorkBuddy scheduling instructions. A terminal
-notification may be delayed by the host; do not replace it with an early worker message.
+New WorkBuddy tasks initialize durable identities with `html next --host-events '[]'`.
+The coordinator sends only incremental events, batched with the next reconciliation:
+`{event:"started",taskId,token}` after native dispatch; and
+`{event:"terminal",taskId,token,outcome:"completed"|"failed"|"cancelled",executionEnded:true}`
+only after verified native execution/retry termination. CLI atomically stores one private
+host-workers.json under the existing coordinator lock. No database, scheduler service,
+model calls or host-private-log dependency. Omitted events and empty arrays never release
+slots; unknown states stay active. Identities and duplicate notifications are checked,
+wrong-token exits and second writers are rejected, replay is idempotent. A repeated started
+event cannot resurrect a terminal worker. `host.workers` provides the current taskId mapping.
+Ready/accept does not release native capacity. Confirmed termination without valid ready
+is returned as host.terminalWithoutHandoff, never automatically redispatched using the old
+token. Retry/pack is blocked while a corresponding/all registered native worker remains active.
+Registration must complete before another allocation/host yield; the CLI cannot observe a
+spawn the host never registers. Native lifecycle evidence remains a host attestation.
+
+Legacy tasks/other hosts can still use `--host-active-tokens` snapshots on next/refill.
+Once durable registration is enabled, snapshots cannot overwrite it. Do not switch a running
+legacy task without accounting for all existing workers. Allocation counts the union of
+native-active and reserved CLI tokens; dispatchTokens excludes all already registered tokens.
+Only dispatch the returned dispatchTokens. An accepted but exiting worker still occupies
+capacity; when HTML is done and workers remain, next=host-wait. No timeout alone releases slots.
+
+host.activeCount means dispatched without confirmed exit, not independently verified running.
+host.slots reports local HTML state, handoff presence and last local artifact activity;
+host.reconcile identifies terminal/reviewed HTML whose native exit remains unconfirmed,
+unknown tokens, or no observed local progress for three/five minutes. These are hints for
+native inspection, not success, timeout failure or authorization to reclaim a slot.
+The coordinator checks each listed native task once on that wakeup, reconciles confirmed
+exits, and refills once. Report deliveredAwaitingExit and unresolved states separately;
+never turn the supplied active array into a claim that every worker is actually generating.
+WorkBuddy can mark a task cancelled while an underlying retry still runs: require confirmed
+execution/retry termination before replacement; unknown states remain reserved and explicit.
+
+html watch --host-active-tokens JSON [--after-state DIGEST --watch-ms 60000] is a bounded
+read-only command outside the queue lock. It reads only this task's local receipts and
+draft metadata, never authentication, browser state or private host logs. It emits a wakeup
+hint on changed handoff/HTML/stall state, or at a 1..60000ms deadline. Routine draft writes
+alone do not wake the model; expired checks never accept, fail, cancel or release workers.
+An after-state digest acknowledges already observed evidence and avoids immediate repeat
+wakeups. next returns a host.watch descriptor for the current/dispatchable tokens.
+The coordinator keeps at most one native background Bash watch, verifies its actual
+background task identity and completion notification capability, and replaces its token
+argument with the workers actually launched if any spawn failed. A stale watch result
+only triggers reconciliation of the current mapping; it cannot overwrite that mapping.
+On a wakeup the host checks only reconcile entries still unresolved in the current mapping
+(batch if supported), then refills once. A deadline with no suspect entries quietly rearms
+the bounded check; it does not query every normally progressing worker or print a report.
+Only rearm while workers remain. No foreground wait/poll loop
+or model watchdog Agent. If background Bash cannot independently notify, disclose this
+limitation instead of claiming guaranteed automatic wakeup. Final cleanup stops only the
+coordinator's own remaining watch. A native status marked cancelled without reliable
+underlying-execution evidence remains an explicit host blocker, not an inferred release.
 
 
 html accept --kind page|form --page-id ID --token TOKEN reads the fixed draft path.
@@ -283,7 +433,7 @@ Status reports pageHtml, collection, formHtml and aggregate html. Pending includ
 ## Fixed offline shell and shared form data
 
 CLI owns the business-blue shell, failure/legacy placeholders and fixed E10FormStore
-transport; host generates business HTML. Full field/control, list-mode, CRUD, detail, comment/log
+transport and a bounded E10FormUI executor; host composes business HTML. Full field/control, list-mode, CRUD, detail, comment/log
 and action-chain expectations ship in templates/form-guide.md, ported from the supplied package. No Preview/Design/Settings top action row.
 Index uses compact neutral blue-gray office styling, with explicit group chevrons,
 progressive indentation and guide lines at every depth, plus active ancestor emphasis.
@@ -310,11 +460,40 @@ Fields bind to field IDs. Generated menus use returned shared records instead of
 private copies; unrelated applications/objects remain isolated. Storage availability is
 browser dependent; in-memory fallback lasts the current session only.
 
+The original supplied prototype/layout-shell/button-isolation guides define the form
+feature scope. Moving operations to fixed code does not add business features, populate
+unconfigured buttons, or remove original requirements. Capability availability is not
+permission. Common fields (text, numbers, dates, choices, local entity selection),
+filter/sort/pagination, main/detail drafts and configured add/view/edit/save/save-and-new/
+cancel/delete have CLI-owned implementations through E10FormUI. AI supplies layout and
+source-bound condition/action decisions; validation rejects unknown fields, wrong modes,
+unsupported operators/actions and unresolved conditions before mutation. Empty/unavailable
+button scopes remain empty/unavailable. No universal permissions/EB rule interpreter.
+
+UI contract derives from this menu's source, has distinct main/detail field keys and exact
+mode/button source pointers. job.behaviorPath is an optional diagnostic copy, not another
+mandatory full-config read. E10FormUI.contract is injected in the offline document. Numeric
+strings preserve decimal and large-ID precision. Draft setters cannot mutate committed
+records; failed validation/cancellation does not save or log changes. A compare-and-save
+checks the previous object state before one local commit; stale snapshots fail retaining
+the draft. This prevents overwrite in the active shell; it is not a multi-browser
+collaboration guarantee. Parent acknowledgement timeouts do not replay writes locally.
+
+The fixed executor covers a subset of the original guide; other original controls/actions
+retain their existing prototype/simulation requirements and must be disclosed, not silently
+reclassified as generic working controls. Files/images/signatures, computed/remote fields,
+workflow references and multi-step business chains are not claimed as newly implemented
+by this basic executor. Capability limitations do not authorize deleting those original
+features from a generated page. CLI render success is not complete interaction verification.
+Same-file host Write/Edit calls are sequential; inspect never rewrites the source draft.
+
 Form initialization must set window.__E10_FORM_READY__=true after data/rendering. Pack
-renders generated form HTML offline at 1440x900, waits ready and checks page errors before
-PNG. Rendering failures mark that HTML failed and block the pack attempt, allowing html
-retry or subsequent explicit PARTIAL packaging. Owned Pages, contexts and Chrome close
-in finally; cleanup failures cannot yield DONE.
+renders the exact generated form HTML by file URL at 1440x900, using the same offline loader
+as inspect with a fresh isolated context per form. Both preserve localStorage origin behavior,
+block external resources, and report initialization/script errors before PNG. Rendering failures mark that HTML failed and block the pack attempt, allowing html
+retry or subsequent explicit PARTIAL packaging. Private pack-diagnostics retain stage, bounded JS errors and browser source locations; errors
+point to focused repair with the existing draft, never a generic full-regeneration instruction.
+Owned Pages, contexts and Chrome close in finally; cleanup failures cannot yield DONE.
 
 ## Delivery and privacy
 
@@ -330,10 +509,31 @@ Exclude credentials, form-input JSON, layout references, real reference record I
 tokens and task state. Manifest carries hashes and specific warnings, not private configs.
 DONE covers supported targets; unsupported skipped menu types still require disclosure.
 
+## CLI command loading
+
+Each invocation remains a short-lived Node process. The entry eagerly loads only built-in
+utilities, common error/output support, host capability checks and host argument parsing.
+Auth, task storage, source collection, HTML queue/review and packaging modules load on the
+selected execution branch. Host-active-token parsing is shared with the lightweight host
+ledger so html watch does not load HTML generation/validation. Keep the html module's
+existing parser export for callers.
+
+playwright-core loads only inside launchChrome, including actual doctor, capture and
+uncached offline rendering. Valid inspection-cache reuse, queue operations, ready/accept,
+status, auth and a blocked host do not initialize the browser library. Commands still
+perform all original receipt/hash, authentication, cleanup and state checks; imports are
+not a substitute for verification. Bootstrap retains per-command runtime file hashes and
+pinned dependency checks, and only installs when ensure finds no valid runtime. No daemon,
+model subprocess, browser reuse across commands or omitted integrity checks is introduced.
+Performance claims distinguish local process startup from WorkBuddy tool/sandbox latency,
+network, capture/render and AI generation time.
+
 ## Runtime distribution
 
-The npm package and Skill installers use https://registry.npmjs.org/ for public
-distribution. Dependencies retain their pinned versions and integrity checks; no
+Publish npm packages to https://registry.npmjs.org/. Skill product.json selects
+https://registry.npmmirror.com for installation, matching the WorkBuddy ui-code-agent
+distribution. Wait for the pinned version to be available in the mirror before delivery.
+Dependencies retain their pinned versions and integrity checks; no
 internal registry is required for installation. Publishing requires explicit user
 authorization and remains separate from local package creation and verification.
 
@@ -420,7 +620,8 @@ verifies initialization/rendering for workflows using __E10_FORM_READY__ just li
 
 ## Bootstrap progress (0.5.4)
 
-Skill first calls read-only status. If not ready, explain once before ensure: “首次使用需要初始化工作环境，大概需要几分钟，完成后自动继续。”
+Skill first calls read-only status and handles the host blocker before any setup. Only
+after host.background=enabled and blocked=false, if runtime is not ready, explain once before ensure: “首次使用需要初始化工作环境，大概需要几分钟，完成后自动继续。”
 Do not expose dependency names in this notice or repeat it during normal ready reuse. Run ensure directly with a 600000ms host command budget, without tail/pipelines.
 Bootstrap emits structured stderr preparation/install/verification/ready progress and a
 15s installation heartbeat; stdout remains one JSON result with elapsedMs on installation.
@@ -454,3 +655,104 @@ a compact associated-form contract. The full original manual remains available a
 referenceGuidePath for targeted lookup, not mandatory full reading. Source configs,
 context fragments, fields, buttons, options, queue concurrency and inspection are
 unchanged. This reduces required guidance, not a claim about total model tokens or latency.
+
+
+## WorkBuddy anomaly recovery (2026-09-17)
+
+Job prompt v15 is generated after detecting the existing regular draft. Recovery begins
+with Read of that draft, preserves completed content and uses bounded edits; only a new
+file begins with a skeleton. Retry still copies a source-verified previous draft to a new
+token and requires confirmed termination of the previous writer. No change to model page
+generation responsibilities, field scope, or visual/functional quality is authorized.
+
+Each dispatchable job includes a short `dispatch` native Agent argument object, with
+`run_in_background:true`, `subagent_type:general-purpose`, readable `name:页面-名称` / `name:表单-名称`,
+description and promptPath instruction. Model is omitted. New WorkBuddy starts submit
+`{"event":"started","receipt":"<unaltered native Spawned successfully. content>"}`
+through --host-events. CLI resolves the persisted dispatchName to token and takes taskId from the same receipt
+regardless of parallel response ordering; missing, ambiguous or synchronous receipts are rejected.
+Legacy explicit taskId/token starts remain supported. Terminal events may omit token;
+CLI resolves the existing taskId, retaining executionEnded:true and outcome requirements.
+An explicit mismatched token is still rejected. Receipts are host-supplied evidence, not
+cryptographically authenticated native state. This does not repair WorkBuddy's acceptance
+of truncated Agent arguments or independently process delayed host notifications.
+File silence at three/five minutes prompts native-state reconciliation; it does not
+prove a stalled model request and never automatically cancels or frees a writer.
+
+`html interact --dir DIR --kind page|form --page-id ID --token TOKEN --steps FILE
+[--width 390]` executes a <=64KB JSON plan with 1..40 steps, ending in an assertion.
+Actions: click/fill/select/press/check/uncheck/reload/assert. Actions target a CSS selector;
+fill/select/press use value. Assert checks visible/hidden/text/value/count; the latter
+three use expected (text is exact innerText). Native dialogs default to dismiss, with
+explicit dialog:accept supported per action. No arbitrary script, dependency installation
+or HTTP server. Canonical prepared HTML and runtimes run in a private offline file context
+with fresh local storage, 30s operation bound plus bounded startup/cleanup. Navigation
+away, new windows, blocked resources, runtime errors and failed assertions fail the check.
+Token-private locking permits parallel workers; source/draft digest is rechecked after
+execution. review/interaction.json records exact steps, per-step results and a final
+screenshot. It proves only those paths. An existing failed/stale interaction receipt blocks
+ready/accept-ready; ready pins its digest. Missing interaction evidence is not proof of
+interaction correctness and remains compatible with previous tasks. No original source
+or completed task is changed during local acceptance fixtures.
+
+html ready returns next=finish-worker and an explicit final-reply instruction; it no longer
+returns notify-coordinator, which conflicted with the native-terminal handoff protocol.
+The coordinator must not broadcast to finished generation teammates, as messages can
+reactivate them after a recorded terminal state. This remains a host lifecycle limitation.
+
+## Readable worker names and cleanup failures (2026-09-17)
+
+New allocations persist dispatchName in HtmlResult before dispatch. Names use 页面-名称
+or 表单-名称; whitespace/path/control punctuation is replaced by hyphens and the label
+is bounded to 60 Unicode characters. Duplicate labels append the item ID; retries append
+重试N; remaining collisions receive a sequence suffix. Names never replace token identity.
+Resume preserves the persisted name; previously allocated jobs keep e10-<token>.
+Original native rename notes are checked and mapped to the requested name, while the
+ledger retains the actual nativeName. Unknown/ambiguous names and explicit token mismatches
+are rejected. Older explicit taskId/token and e10-token receipts remain supported.
+
+CLI emits the final output only after lock release, so release failures cannot follow an
+already-emitted success JSON. SAFE_DELETE_BULK_CONFIRM_REQUIRED / SAFE_DELETE_BULK_REJECTED
+are explicit error codes with stop/reconcile guidance, not generic retry instructions.
+The original host guard marker is emitted unescaped on stderr. Structured stdout keeps
+the code and diagnostic details but does not duplicate the raw marker inside JSON strings:
+WorkBuddy parses the first marker in combined stdout/stderr as an unescaped JSON payload.
+This preserves its normal approval path; it does not grant permission or change guard scope.
+Lock cleanup failure reports operationCompleted plus any original operationError and
+cleanupError; true means the action returned, not that the whole command succeeded.
+Atomic JSON writes remove temporary files only on failure, retaining both errors if
+cleanup also fails. Removing nonexistent temporary files did not count toward the host
+bulk guard; this change does not eliminate real lock cleanup confirmations.
+
+Workers/coordinators stop automatic retries on these host guard errors, preserve existing
+work, and use the host's normal approval flow before reconciliation. Never manually
+remove lock directories, change deletion mechanisms or security settings to bypass the
+block. Keep required interaction coverage; static assertions cannot replace the requested
+save/cancel path. The CLI does not change WorkBuddy approval scope or suppress prompts.
+
+
+## Lightweight worker and coordinator guidance (0.5.7, prompt 17)
+
+Keep page generation responsibilities, Skill concurrency eight, host-default/auto models,
+existing validation and deletion behavior. Prefer same-turn independent dispatch calls,
+batched immediate registration, then terminal reconciliation/refill before progress prose.
+Preserve jobs/dispatch/watch output instead of stripping and fetching it again. Watch rearming
+retains the latest after-state digest and uses background notifications, not foreground polling.
+Every submitted terminal must have the matching native identity's notification/status evidence;
+a different task's completion, ready or watch completion never proves that worker exited.
+These are host instructions, not a deterministic scheduler or independently verified lifecycle.
+
+Workers do not create/claim shared task-list items or browse sibling tokens. Missing private
+review directories are normal. After ready they return a concise final answer without further
+tool calls. Normal delivery uses pack results; detailed timing audits are only done on request.
+Reports distinguish native Started/Ended, ledger registration/release, HTML acceptance and host
+reclamation, calculate durations from timestamps and disclose early release as an anomaly.
+
+Interaction plans remain strict objects with steps arrays; count expected is an integer 0..10000,
+text/value expected and fill/select/press value are strings. Invalid plans return the same code
+plus details.field, one-based details.step where applicable, and the expected format. The parser
+does not coerce strings to numbers or run the browser for malformed input. Fix the plan alone
+when the HTML did not change. All-row claims require all-row assertions, not first/last samples.
+Form query validation keeps its current accepted inputs and bounds but names the failing
+filters/sort/pageSize/page field. The compact guide documents arrays, pageSize 1..500 and using
+orderedIds plus snapshot records for full filtered totals, without expanding business features.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "e10-ebuilder-prototype",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Generate offline E10 application prototypes from published page, modeling-list and workflow menus",
   "type": "module",
   "license": "UNLICENSED",