browser-workspace 0.4.1 → 0.4.5

package/README.md

@@ -20,13 +20,13 @@ browser-workspace session stop SESSION_ID
 
 `--workspace` is hidden from normal CLI help. Normal sessions use `Harness`; product integrations may set an explicit workspace internally when they require isolation.
 
-`session stop` closes all tabs created/owned by that session while leaving unrelated browser tabs untouched.
+`session stop` closes all tabs created/owned by that session while leaving unrelated browser tabs untouched. Raw session CDP cannot create targets: `Target.createTarget` is rejected and callers must use `new_tab()` so workspace/session ownership is preserved.
 
 ## Included layers
 
 ```text
 browser-workspace
-├── src/browser_harness/     low-level browser/CDP runtime (forked internally)
+├── pyproject.toml           pins the external browser-harness runtime dependency
 ├── agent-workspace/         Browser Workspace helper layer
 ├── extension/               Chrome workspace/tab manager
 ├── session_daemon.py        persistent Python session service
@@ -136,3 +136,17 @@ Each platform manifest records explicit verification status and evidence. `verif
 ## npx skills installation
 
 After `npx skills add ...`, invoke `~/.agents/skills/browser-workspace/bin/browser-workspace` directly. The first session start bootstraps the skill-owned Python virtual environment automatically; running `scripts/install.sh` is optional.
+
+### Python distribution (PyPI)
+
+Browser Workspace is also packaged as a Python CLI. Once its PyPI trusted publisher is configured and a `pypi-v*` release tag is published, invoke it with:
+
+```bash
+uvx browser-workspace status
+uvx browser-workspace session list
+uvx browser-workspace platform profile wechat-channels
+```
+
+The package entry point is `browser_workspace_app.cli:main`, and Python dependencies are managed by `pyproject.toml`. This uses the same existing Chrome profile and Session Daemon socket as the previous npm CLI; it does **not** start a second browser or daemon when the existing one is healthy.
+
+Before building, run `python tools/sync-pypi-package.py` to copy canonical Python and packaged platform assets to the wheel source. Run `uv build`, then validate with `uvx --from dist/browser_workspace-<version>-py3-none-any.whl browser-workspace status`. The PyPI publishing workflow uses GitHub OIDC trusted publishing; configure `lalalic/browser-workspace` with the `pypi` environment as the publisher on PyPI before the first tag release.

package/SKILL.md

@@ -9,31 +9,33 @@ Browser Workspace is the **only browser skill agents should load**. It includes
 
 ## Agent contract
 
-When installed with `npx skills`, use the CLI from the skill itself; no separate install step is required:
+Install the Skill instructions through your preferred skill manager, but run the published Python CLI through **PyPI/uvx**. The Skill directory is documentation, not the executable source of truth:
 
 ```bash
-BW_CLI="$HOME/.agents/skills/browser-workspace/bin/browser-workspace"
-$BW_CLI status
+bw() { uvx browser-workspace "$@"; }
+bw status
 ```
 
-On first use, Browser Workspace bootstraps its own `.venv` automatically.
+On first use, `uvx` installs Browser Workspace and Python dependencies from PyPI into its managed cache. No local source checkout, `.venv`, `.env`, or `npx` CLI is required. Use `uvx browser-workspace ...` consistently, including in NeoY/Agents Relay workers.
 
-Use one of two execution paths:
+Use one session-owned execution path for orchestrated browser work:
 
 ```text
-known platform flow
-  -> $BW_CLI platform run <platform> <action> [--config FILE]
-  -> runner creates the browser session
-  -> runner executes the platform action
-  -> runner always stops and cleans up
-
-custom browser workflow
-  -> $BW_CLI session start
-  -> $BW_CLI session exec <session_id>
-  -> $BW_CLI session stop <session_id>
+start one Browser Workspace session
+  -> retain SESSION_ID for the whole workflow
+  -> platform run <platform> <action> --session-id SESSION_ID
+  -> inspect each result
+  -> on recoverable failure, diagnose and self-heal in the SAME session
+  -> write every successful site-specific repair back to the platform code
+  -> continue until the external workflow reaches a terminal outcome
+  -> verify the terminal external state
+finally
+  -> stop SESSION_ID
 ```
 
-Do not manually create a session around a platform action unless product code intentionally owns a longer-lived browser context. There are no separate top-level `open`, `tabs`, `status`, or `screenshot` commands.
+`platform run` therefore requires `--session-id` by default. If omitted, the CLI returns a structured error that recommends the `session start -> platform run --session-id -> self-heal -> session stop` workflow. `--auto-session` is an explicit one-shot escape hatch: it creates and cleans up a temporary session automatically, but **does not provide orchestrator self-heal** after failure.
+
+There are no separate top-level `open`, `tabs`, `status`, or `screenshot` commands.
 
 Every logical browser workflow must follow:
 
@@ -59,7 +61,7 @@ Rules:
 Default workspace is `Harness`:
 
 ```bash
-$BW_CLI session start
+bw session start
 ```
 
 Normal agents do not choose or manage workspaces. `session start` defaults to `Harness`; the `--workspace` implementation option is hidden from normal CLI help. Workspace lifecycle is not exposed through the agent CLI. Product runtimes that need persistent isolation discover the product-only Node admin helper with `browser-workspace status`, then call `ensureWorkspace` / `deleteWorkspace` through that helper.
@@ -67,7 +69,7 @@ Normal agents do not choose or manage workspaces. `session start` defaults to `H
 Start directly at a URL when known:
 
 ```bash
-$BW_CLI session start --url https://example.com
+bw session start --url https://example.com
 ```
 
 The result is JSON containing `session_id`, `workspace`, `target_id`, the starting `url`, and `workspace_supported`.
@@ -79,7 +81,7 @@ Browser Workspace self-manages exactly one machine-wide persistent, visible Chro
 `session exec` reads Python from stdin. Helpers are already imported; do not import another browser package.
 
 ```bash
-$BW_CLI session exec <session_id> <<'PY'
+bw session exec <session_id> <<'PY'
 print(page_info())
 print(snapshot())
 PY
@@ -88,7 +90,7 @@ PY
 Python state persists across later calls in the same session:
 
 ```bash
-$BW_CLI session exec <session_id> <<'PY'
+bw session exec <session_id> <<'PY'
 meeting_name = "Demo"
 print(current_tab())
 PY
@@ -97,7 +99,7 @@ PY
 Then later:
 
 ```bash
-$BW_CLI session exec <session_id> <<'PY'
+bw session exec <session_id> <<'PY'
 print(meeting_name)
 PY
 ```
@@ -107,19 +109,19 @@ A Python file may also be used with `--code-file`.
 ## Stop
 
 ```bash
-$BW_CLI session stop <session_id>
+bw session stop <session_id>
 ```
 
-Stopping closes every tab owned or opened by that session—including tabs created with `new_tab()`, `bh.new_tab()`, direct `Target.createTarget`, and detected child/popup tabs—then destroys the session's Python namespace. It does not close unrelated browser tabs. Do not reuse the ID afterward.
+Stopping closes every tab owned or opened by that session—including tabs created with `new_tab()`, `bh.new_tab()`, and detected child/popup tabs—then destroys the session's Python namespace. Raw `cdp("Target.createTarget", ...)` is rejected; use `new_tab()` so Browser Workspace can own and group the tab. It does not close unrelated browser tabs. Do not reuse the ID afterward.
 
 A safe shell structure is:
 
 ```bash
-SESSION_JSON=$($BW_CLI session start)
+SESSION_JSON=$(bw session start)
 SESSION_ID=$(python3 -c 'import json,sys; print(json.loads(sys.argv[1])["session_id"])' "$SESSION_JSON")
-trap '$BW_CLI session stop "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
+trap 'bw session stop "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
 
-$BW_CLI session exec "$SESSION_ID" <<'PY'
+bw session exec "$SESSION_ID" <<'PY'
 print(snapshot())
 PY
 ```
@@ -216,21 +218,41 @@ platforms/<name>/
 
 Platform rules:
 
-- Platform actions may use browser helpers such as `new_tab()`, `current_tab()`, `snapshot()`, `js()`, `cdp()`, uploads, downloads, and screenshots.
+- Platform actions may use semantic browser helpers such as `new_tab()`, `current_tab()`, `snapshot()`, `click(selector)`, `fill_input(selector, text)`, `js()`, `cdp()`, uploads, downloads, and screenshots. `cdp()` must not create targets; `Target.createTarget` is blocked and tab creation must use `new_tab()`.
+- Platform interaction code must be **semantic and element-based**. It must not use screen coordinates, viewport coordinates, `x/y` click targets, `click_at_xy()`, or coordinate calculations to interact with the page. Browser size, zoom, display resolution, and viewport geometry must not affect correctness.
 - Platform actions must **not** create/stop Browser Workspace sessions, choose a workspace, call workspace-management APIs, invoke the Browser Workspace CLI, or import session/workspace infrastructure.
+- The orchestrator owns the session lifecycle for normal platform execution: start once, retain the same session across execution and recovery, and stop only after terminal success, terminal failure, or an explicit human blocker.
+- On any recoverable failure, the orchestrator must inspect the live page in the same session, diagnose the failure, repair/recover, and resume from the safest point rather than restarting the whole workflow.
+- **Self-heal writeback is mandatory:** if recovery discovers a site-specific selector, flow, wait condition, validation rule, or other adapter fix that makes the action work, write that repair back to `platforms/<name>/actions/` (and update platform docs/verification metadata when applicable) before declaring the workflow complete. A repair that exists only in an ad-hoc session snippet is not complete.
+- After a possible external side effect (publish, send, payment, delete, submit, etc.), recovery must be verification-first. Never repeat the side effect until read-only evidence proves the previous attempt did not take effect.
 - Platform `README.md` and flow docs should describe site behavior, preconditions, side effects, and verification evidence—not Browser Workspace lifecycle mechanics.
-- Platform actions must remain usable in either a generic runner-owned session or a product-owned browser context.
-- The generic runner owns the normal lifecycle: start a default Harness session, inject browser helpers/config, execute the action, then always stop the session and close its owned tabs.
-- Products that require a dedicated or persistent browser context (for example Family Tutor or Agents Relay) may execute the same platform action inside product-owned infrastructure. The platform code itself stays unchanged.
 - Do not rediscover a known site's mechanics when a verified platform flow/action already exists.
 
-Run a platform action through the generic runner:
+Normal orchestrator workflow:
+
+```bash
+SESSION_JSON=$(bw session start --url https://example.com)
+SESSION_ID=$(python3 -c 'import json,sys; print(json.loads(sys.argv[1])["session_id"])' "$SESSION_JSON")
+
+bw platform run microsoft-teams meeting \
+  --session-id "$SESSION_ID" \
+  --config /path/to/config.json
+
+# If it fails: inspect/self-heal using the same SESSION_ID, write the repair
+# back to the platform implementation, then resume safely.
+
+bw session stop "$SESSION_ID"
+```
+
+One-shot mode is explicit and is not self-healing:
 
 ```bash
-$BW_CLI platform run microsoft-teams meeting --config /path/to/config.json
+bw platform run microsoft-teams meeting \
+  --auto-session \
+  --config /path/to/config.json
 ```
 
-The runner output hides the raw session ID. It returns the platform/action result, optional workspace-extension warning, and cleanup evidence.
+Use `--auto-session` only when losing the browser state after a failure is acceptable.
 
 ### Platform verification contract
 
@@ -274,13 +296,14 @@ Read the matching platform `README.md` and `manifest.yaml` before invoking or mo
 
 ## Installation
 
-Run the bundled installer from the skill directory:
+Use the published PyPI command (requires `uv`/`uvx`):
 
 ```bash
-./scripts/install.sh
+uvx browser-workspace status
+uvx browser-workspace session list
 ```
 
-It creates a Browser Workspace-owned `.venv`, installs the vendored browser runtime and dependencies, writes Browser Workspace environment configuration to `agent-workspace/.env`, and links `browser-workspace` into `~/.local/bin` by default.
+`uvx` resolves the published Python wheel and installs the dependencies declared in `pyproject.toml`. Do not run the legacy bundled installer or point agents at a checked-out `bin/browser-workspace` script. The installed CLI reuses the same Browser Workspace Chrome profile and Session Daemon socket.
 
 There is no required separate Browser Harness installation.
 
@@ -298,4 +321,4 @@ kgbghhigmbpefppgkocgjgnnnbhjchic
 
 ## Internal provenance
 
-The low-level browser runtime is forked from `browser-use/browser-harness` and kept internally under `src/browser_harness/`. Browser Workspace is the public product/skill/CLI surface. Upstream licensing is preserved under `licenses/`.
+The low-level browser runtime is the separately maintained `browser-harness` Python dependency. Browser Workspace owns the session/workspace/platform product layer and pins the exact Harness runtime revision it was tested with; Harness source is not vendored into this repository. Upstream licensing remains documented under `licenses/`.

package/bin/browser-workspace

@@ -30,18 +30,165 @@ def status():
     }
 
 def main():
-    p=argparse.ArgumentParser(prog='browser-workspace')
-    sp=p.add_subparsers(dest='group',required=True)
-    sp.add_parser('status')
-    session=sp.add_parser('session'); ssp=session.add_subparsers(dest='cmd',required=True)
-    start=ssp.add_parser('start'); start.add_argument('--workspace', help=argparse.SUPPRESS); start.add_argument('--url')
-    ssp.add_parser('list')
-    ex=ssp.add_parser('exec'); ex.add_argument('session_id'); ex.add_argument('--code-file')
-    stop=ssp.add_parser('stop'); stop.add_argument('session_id', nargs='?'); stop.add_argument('--all', action='store_true', dest='stop_all')
-    platform=sp.add_parser('platform'); psp=platform.add_subparsers(dest='pcmd',required=True)
-    profile=psp.add_parser('profile'); profile.add_argument('platform')
-    source=psp.add_parser('source'); source.add_argument('platform'); source.add_argument('action'); source.add_argument('--config')
-    run=psp.add_parser('run'); run.add_argument('platform'); run.add_argument('action'); run.add_argument('--config'); run.add_argument('--url'); run.add_argument('--session-id')
+    fmt=argparse.RawDescriptionHelpFormatter
+    p=argparse.ArgumentParser(
+        prog='browser-workspace',
+        description='Control the shared Browser Workspace Chrome, browser sessions, and platform automations.',
+        epilog='''Examples:
+  browser-workspace status
+  browser-workspace session start --url https://example.com
+  browser-workspace session list
+  browser-workspace session exec SESSION_ID --code-file script.py
+  browser-workspace session stop SESSION_ID
+  browser-workspace session stop --all
+  browser-workspace platform profile wechat-channels
+  browser-workspace platform run wechat-channels manage --session-id SESSION_ID --config status.json
+  browser-workspace platform run wechat-channels post --session-id SESSION_ID --config post.json
+  browser-workspace platform run wechat-channels manage --auto-session --config status.json
+''',
+        formatter_class=fmt,
+    )
+    sp=p.add_subparsers(dest='group',required=True,title='commands',metavar='COMMAND')
+
+    sp.add_parser(
+        'status',
+        help='Show Browser Workspace runtime, managed Chrome, daemon, and active-session status.',
+        description='Show Browser Workspace runtime, managed Chrome, daemon, and active-session status.',
+        epilog='Example:\n  browser-workspace status',
+        formatter_class=fmt,
+    )
+
+    session=sp.add_parser(
+        'session',
+        help='Create, inspect, execute code in, and stop browser sessions.',
+        description='Manage Browser Workspace sessions.',
+        epilog='''Examples:
+  browser-workspace session start --url https://example.com
+  browser-workspace session list
+  browser-workspace session exec SESSION_ID --code-file script.py
+  cat script.py | browser-workspace session exec SESSION_ID
+  browser-workspace session stop SESSION_ID
+  browser-workspace session stop --all
+''',
+        formatter_class=fmt,
+    )
+    ssp=session.add_subparsers(dest='cmd',required=True,title='session commands',metavar='COMMAND')
+
+    start=ssp.add_parser(
+        'start',
+        help='Start a browser session, optionally opening a URL.',
+        description='Start a browser session. The shared managed Chrome is reused; this does not launch a separate browser per session.',
+        epilog='''Examples:
+  browser-workspace session start
+  browser-workspace session start --url https://example.com
+''',
+        formatter_class=fmt,
+    )
+    start.add_argument('--workspace', help=argparse.SUPPRESS)
+    start.add_argument('--url', metavar='URL', help='URL to open when the session starts.')
+
+    ssp.add_parser(
+        'list',
+        help='List currently active Browser Workspace sessions.',
+        description='List currently active Browser Workspace sessions and their target tabs.',
+        epilog='Example:\n  browser-workspace session list',
+        formatter_class=fmt,
+    )
+
+    ex=ssp.add_parser(
+        'exec',
+        help='Execute Browser Workspace Python helpers inside an existing session.',
+        description='Execute Python using Browser Workspace helpers in an existing session. Read code from --code-file or stdin.',
+        epilog='''Examples:
+  browser-workspace session exec SESSION_ID --code-file script.py
+
+  browser-workspace session exec SESSION_ID <<'PY'
+  print(page_info())
+  print(snapshot(interactive_only=False))
+  PY
+''',
+        formatter_class=fmt,
+    )
+    ex.add_argument('session_id', metavar='SESSION_ID', help='Session ID returned by "session start" or "session list".')
+    ex.add_argument('--code-file', metavar='PATH', help='Read Python code from this file instead of stdin.')
+
+    stop=ssp.add_parser(
+        'stop',
+        help='Stop one session or all sessions and release their Browser Workspace tabs.',
+        description='Stop one Browser Workspace session, or all sessions with --all.',
+        epilog='''Examples:
+  browser-workspace session stop SESSION_ID
+  browser-workspace session stop --all
+''',
+        formatter_class=fmt,
+    )
+    stop.add_argument('session_id', nargs='?', metavar='SESSION_ID', help='Session ID to stop.')
+    stop.add_argument('--all', action='store_true', dest='stop_all', help='Stop all active Browser Workspace sessions.')
+
+    platform=sp.add_parser(
+        'platform',
+        help='Inspect and run reusable website-specific platform automations.',
+        description='Inspect and run reusable Browser Workspace platform automations.',
+        epilog='''Examples:
+  browser-workspace platform profile wechat-channels
+  browser-workspace platform source wechat-channels post --config post.json
+  browser-workspace session start --url https://channels.weixin.qq.com/platform/post/list
+  browser-workspace platform run wechat-channels manage --session-id SESSION_ID --config status.json
+  browser-workspace platform run wechat-channels post --session-id SESSION_ID --config post.json
+  browser-workspace session stop SESSION_ID
+
+One-shot mode (no orchestrator self-heal):
+  browser-workspace platform run wechat-channels manage --auto-session --config status.json
+''',
+        formatter_class=fmt,
+    )
+    psp=platform.add_subparsers(dest='pcmd',required=True,title='platform commands',metavar='COMMAND')
+
+    profile=psp.add_parser(
+        'profile',
+        help='Show a platform manifest/profile: fields, media rules, and capabilities.',
+        description='Show the declared Browser Workspace profile for a platform.',
+        epilog='Example:\n  browser-workspace platform profile wechat-channels',
+        formatter_class=fmt,
+    )
+    profile.add_argument('platform', metavar='PLATFORM', help='Platform name, for example "wechat-channels".')
+
+    source=psp.add_parser(
+        'source',
+        help='Print the fully prepared Python source for one platform action without running it.',
+        description='Render the action source after injecting the optional JSON config path. No browser action is executed.',
+        epilog='''Examples:
+  browser-workspace platform source wechat-channels post --config post.json
+  browser-workspace platform source wechat-channels manage --config status.json
+''',
+        formatter_class=fmt,
+    )
+    source.add_argument('platform', metavar='PLATFORM', help='Platform name, for example "wechat-channels".')
+    source.add_argument('action', metavar='ACTION', help='Declared action name, for example "post" or "manage".')
+    source.add_argument('--config', metavar='PATH', help='JSON configuration file used to prepare the action.')
+
+    run=psp.add_parser(
+        'run',
+        help='Run one platform action in Browser Workspace.',
+        description='Run a declared platform action. A caller-owned --session-id is required by default so an orchestrator can inspect failures, self-heal in the same browser state, write repairs back to platform code, and close the session only after completion. --auto-session is an explicit one-shot mode without orchestrator self-heal.',
+        epilog='''Examples:
+  browser-workspace session start --url https://channels.weixin.qq.com/platform/post/list
+  browser-workspace platform run wechat-channels manage --session-id SESSION_ID --config status.json
+  browser-workspace platform run wechat-channels post --session-id SESSION_ID --config post.json
+  browser-workspace session stop SESSION_ID
+
+One-shot mode (no orchestrator self-heal):
+  browser-workspace platform run wechat-channels manage --auto-session --config status.json
+''',
+        formatter_class=fmt,
+    )
+    run.add_argument('platform', metavar='PLATFORM', help='Platform name, for example "wechat-channels".')
+    run.add_argument('action', metavar='ACTION', help='Declared action name, for example "post" or "manage".')
+    run.add_argument('--config', metavar='PATH', help='JSON configuration file for the platform action.')
+    run.add_argument('--url', metavar='URL', help='Optional initial URL for a temporary session.')
+    session_mode = run.add_mutually_exclusive_group()
+    session_mode.add_argument('--session-id', metavar='SESSION_ID', help='Required by default. Reuse a caller-owned session so failures can be inspected and self-healed before the session is closed.')
+    session_mode.add_argument('--auto-session', action='store_true', help='Explicit one-shot mode: create and clean up a temporary session automatically. No orchestrator self-heal is available after failure.')
     args=p.parse_args()
     if args.group=='status': emit(status()); return
     if args.group=='session' and args.cmd=='list':
@@ -71,5 +218,19 @@ def main():
         from platform_runner import platform_profile
         emit(platform_profile(args.platform)); return
     if args.group=='platform' and args.pcmd=='run':
-        r=run_platform_action(args.platform,args.action,config_path=args.config,url=args.url,session_id=args.session_id); emit(r); raise SystemExit(0 if (r.get('result') or {}).get('ok',False) else 1)
+        if not args.session_id and not args.auto_session:
+            emit({
+                'ok': False,
+                'error': 'session_id_required',
+                'message': 'platform run requires --session-id by default so the orchestrator can self-heal failures in the same browser session.',
+                'suggested_workflow': [
+                    'browser-workspace session start --url <URL>',
+                    'browser-workspace platform run <PLATFORM> <ACTION> --session-id SESSION_ID [--config FILE]',
+                    'inspect/self-heal failures in the same SESSION_ID and write successful repairs back to platform code',
+                    'browser-workspace session stop SESSION_ID',
+                ],
+                'auto_session': 'Use --auto-session only for a one-shot run. It creates and closes its own session and does not provide orchestrator self-heal.',
+            })
+            raise SystemExit(2)
+        r=run_platform_action(args.platform,args.action,config_path=args.config,url=args.url,session_id=args.session_id,auto_session=args.auto_session); emit(r); raise SystemExit(0 if (r.get('result') or {}).get('ok',False) else 1)
 if __name__=='__main__': main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-workspace",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "description": "Agent browser workspace with persistent sessions, tab leasing, snapshots, and platform workflows.",
   "bin": {
     "browser-workspace": "bin/browser-workspace"

package/platform_runner.py

@@ -102,11 +102,16 @@ def declared_actions(platform: str) -> dict[str, Path]:
         raise ValueError(f"{platform}/manifest.yaml has no actions block")
 
     actions: dict[str, Path] = {}
-    for name, relative in re.findall(
-        r'^\s{2}([\w-]+):\s*["\']([^"\']+)["\']\s*$',
-        match.group("body"),
-        flags=re.MULTILINE,
-    ):
+    for line in match.group("body").splitlines():
+        entry = re.match(r'^\s{2}([\w-]+):\s*(.+?)\s*$', line)
+        if not entry:
+            continue
+        name, relative = entry.groups()
+        if len(relative) >= 2 and relative[0] == relative[-1] and relative[0] in {"\"", "'"}:
+            relative = relative[1:-1]
+        # Actions are simple relative file paths; comments and nested mappings are not runnable actions.
+        if not relative or relative.startswith(("#", "{", "[")) or " #" in relative:
+            continue
         path = PLATFORMS / platform / relative
         if not path.is_file():
             raise FileNotFoundError(f"declared platform action missing: {platform}/{name} -> {relative}")
@@ -146,6 +151,7 @@ def run_platform_action(
     config_path: str | None = None,
     url: str | None = None,
     session_id: str | None = None,
+    auto_session: bool = False,
 ) -> dict:
     path = action_path(platform, action)
     config_file = Path(config_path) if config_path else None
@@ -156,7 +162,16 @@ def run_platform_action(
         validate_platform_config(platform, action, config)
     code = prepare_action(path, config_file)
 
-    owned_session = not bool(session_id)
+    if not session_id and not auto_session:
+        raise ValueError(
+            "platform run requires session_id; orchestrators should use: "
+            "session start -> platform run --session-id SESSION_ID -> self-heal in the same session -> session stop. "
+            "Use auto_session=True only for a one-shot run without orchestrator self-heal."
+        )
+    if session_id and auto_session:
+        raise ValueError("session_id and auto_session are mutually exclusive")
+
+    owned_session = bool(auto_session)
     started = request({"op": "start", "workspace": None, "url": url}) if owned_session else {"session_id": session_id, "workspace_supported": None}
     sid = started["session_id"]
     result = None
@@ -168,6 +183,8 @@ def run_platform_action(
             "platform": platform,
             "action": action,
             "workspace_supported": started.get("workspace_supported"),
+            "session_mode": "auto_session_no_self_heal" if owned_session else "caller_owned_self_heal_capable",
+            "self_heal_capable": not owned_session,
             "result": result,
         }
         if started.get("warning"):

package/platforms/chatgpt/actions/_temporary_submit.py

@@ -439,7 +439,14 @@ def _fill_prompt_if_needed(prompt, mode_label, timeout=30):
     deadline = time.time() + timeout
     last_error = None
     while time.time() < deadline:
-        selector = _wait_for_composer(timeout=min(5, max(1, deadline - time.time())))
+        try:
+            selector = _wait_for_composer(timeout=min(5, max(1, deadline - time.time())))
+        except RuntimeError as exc:
+            # Hydration and navigation can temporarily remove the composer.
+            # Continue the outer readiness window rather than aborting on the first poll.
+            last_error = exc
+            time.sleep(.25)
+            continue
         if prompt_text_matches(_composer_text(selector), prompt):
             return selector
 
@@ -567,5 +574,18 @@ while time.time() < deadline:
 else:
     raise RuntimeError("Temporary Chat activation was not observed")
 
-result = _submit_current_page(prompt, temporary=True, mode_label="Temporary Chat")
+try:
+    result = _submit_current_page(prompt, temporary=True, mode_label="Temporary Chat")
+except RuntimeError as exc:
+    # A URL-prefilled Temporary Chat can retain the pre-hydration home input
+    # without ever mounting the active composer. No send occurred, so retry
+    # once on a clean Temporary Chat page without URL prompt prefill.
+    if "composer readiness was not observed ready" not in str(exc):
+        raise
+    goto_url(temporary_chat_entry_url())
+    wait_for_load()
+    _click_temporary_chat_toggle()
+    if not _temporary_chat_enabled():
+        raise RuntimeError("Temporary Chat mode lost during composer recovery") from exc
+    result = _submit_current_page(prompt, temporary=True, mode_label="Temporary Chat")
 print(json.dumps(result, ensure_ascii=False), flush=True)

package/platforms/chatgpt/tests/test_contract.py

@@ -174,3 +174,10 @@ def test_new_turn_project_id_is_optional():
     assert 'if not thread_id: raise RuntimeError("thread_id is required")' in turn
     assert 'https://chatgpt.com/c/{quote(thread_id' in turn
     assert 'https://chatgpt.com/g/{quote(project_id' in turn
+
+
+def test_temporary_submit_recovers_only_before_send_from_prefill_hydration():
+    code=(ACTIONS/"_temporary_submit.py").read_text()
+    assert 'goto_url(temporary_chat_entry_url())' in code
+    assert '"composer readiness was not observed ready" not in str(exc)' in code
+    assert 'if not _temporary_chat_enabled():' in code

package/platforms/wechat-channels/actions/_common.py

@@ -6,7 +6,7 @@ import re
 from typing import Any, Optional
 from urllib.parse import parse_qs, urlparse
 
-MANAGER_URL = "https://channels.weixin.qq.com/platform/post"
+MANAGER_URL = "https://channels.weixin.qq.com/platform/post/list"
 
 STATUS_LABELS: tuple[tuple[str, str], ...] = (
     ("审核中", "reviewing"),