# 2026-07-07 MDEDC03 App 侧首启诊断

## 用户目标

PMO 派发 `MD-EDC-03`，要求 Coder@mindraw 只查 Mindraw App 侧 fresh-path bootstrap blocker：在 Mindraw App 未手动启动前，Codex sidebar 显示 `MINDRAW_PREVIEW_SOURCE_REQUIRED` / `MINDRAW_OPEN_PACKAGE_API_REQUIRED`，点击 `Edit` 不能启动 App；手动启动 App 后 sidebar preview 恢复。

边界：不改 m4c plugin/runtime/sidebar，不声明 QA PASS / 用户验收 / 公开发布。

## 已完成事项

- 按项目读取顺序复核 `AGENTS.md`、`INDEX.md`、`02-P/plan-progress.markdown` 中 `P-20260707-signed-notarized-dmg`、`CODEGRAPH.md`、MD-EDC-03 dispatch brief 和 MEXP15 / MD-EDC-02 / QA-EDC-04 / blocker 证据。
- 只读核对 App 侧关键源码：App API capability 写入、`.mindraw` open-documents handler、`mindraw://` deep link、前端 App API transport、`mindraw.app.open_package`。
- 从 MEXP15 DMG 提取 `1.2.4 / Build202607071930` 候选 App 到 `/tmp` 验证冷启动。
- 做一次可恢复 `/Applications/Mindraw.app` 临时安装验证：先备份原 `1.2.3 / Build202607042351`，放入候选 `1.2.4 / Build202607071930`，注册 LaunchServices，验证后恢复原 App。
- 写入 Coder 自查报告：`02-P/MEXP15-SignedNotarizedDMG/qa/md-edc-03-fresh-path-bootstrap-check-20260707.md`。
- 更新统一台账 `02-P/plan-progress.markdown` 和 `INDEX.md`。

## 关键决策

结论：`APP_SIDE_NOT_ROOT_CAUSE`。

证据显示 MEXP15 signed / notarized App 被 macOS 外部入口调用时可以完成 App 侧 bootstrap：

- `open -a /Applications/Mindraw.app` 可在 App 未运行时冷启动并生成 healthy `runtime/write-api.json`。
- `.mindraw` 默认 handler 可冷启动 App、生成 capability，并打开 package 为 active tab。
- `mindraw://` 默认 handler 可冷启动 App、生成 capability，并打开已登记 document link。
- App API 暴露 `mindraw.app.open_package`、`mindraw.app.get_preview_snapshot`、`mindraw.app.get_open_document_state` 等 project canvas 方法。

用户看到的 blocker 仍然成立，但从 App 侧证据看，不是 Mindraw App 无法冷启动或无法暴露 runtime capability。下一步应由 `M4C-EDC-03` / PMO 判断 sidebar 在 capability 缺失时是否应主动 launch App、等待 capability、retry 或给用户非死路提示。

## 核心事实 / 变更快照

- 变更对象：MEXP15 `P-20260707-signed-notarized-dmg` 中 `MD-EDC-03` 任务状态和证据入口。
- 事实来源：
  - `02-P/MEXP15-SignedNotarizedDMG/qa/md-edc-03-fresh-path-bootstrap-check-20260707.md`
  - `02-P/plan-progress.markdown`
  - `INDEX.md`
- 变更前：`MD-EDC-03` 为待诊断；MEXP15 状态为等待 `MD-EDC-03` 和 `M4C-EDC-03` 并行定位。
- 变更后：`MD-EDC-03` 标记为 App 侧诊断完成，结果 `APP_SIDE_NOT_ROOT_CAUSE`；MEXP15 仍 blocked，下一步 pending `M4C-EDC-03` sidebar fallback。
- 范围边界：未改源码、配置、构建脚本、m4c、候选 DMG、installed cache；未创建新 Review Gate；未生成新 JSON，因为无代码改动。
- 验证证据：
  - copied candidate metadata: `1.2.4 / Build202607071930 / com.mindraw.desktop`
  - doctor copied candidate with App API capability: `status=pass`
  - temporary `/Applications` doctor system handlers: `status=pass`
  - `open -a /Applications/Mindraw.app`: health `ok=true`
  - `open <package>.mindraw`: document state `ok=true`
  - `open 'mindraw://...'`: document state `ok=true`
  - restore check: `/Applications/Mindraw.app` back to `1.2.3 / Build202607042351`; `Mindraw` process absent; runtime capability absent

## 文件变更

- 新增：`02-P/MEXP15-SignedNotarizedDMG/qa/md-edc-03-fresh-path-bootstrap-check-20260707.md`
- 修改：`02-P/plan-progress.markdown`
- 修改：`INDEX.md`
- 新增：`.codex-sessionhistory/2026-07-07-MDEDC03App诊断.md`
- 修改：`.codex-sessionhistory/COMMANDS.md`

## 可复用命令 / Runbook

用途：复查 signed / notarized Mindraw App 候选是否能在未运行状态下通过 macOS 外部入口完成 App 侧 bootstrap。

前置条件：

- DMG 已存在，例如 `Mindraw_1.2.4_aarch64-Build202607071930.dmg`。
- 当前没有用户正在使用 Mindraw；如需覆盖 `/Applications/Mindraw.app`，必须先备份并在测试后恢复。
- 不输出或记录 App API capability token。

设置命令：

```bash
DMG='/private/tmp/mindraw-md-edc-02-signed-notarized-20260707/03-O/C2.builds/releases/Build202607071930/Mindraw_1.2.4_aarch64-Build202607071930.dmg'
APP_COPY_ROOT='/tmp/mindraw-md-edc-03-app-r1'
APP_COPY="$APP_COPY_ROOT/Mindraw.app"
rm -rf "$APP_COPY_ROOT"
mkdir -p "$APP_COPY_ROOT"
MOUNT_OUTPUT=$(hdiutil attach -readonly -nobrowse "$DMG")
MOUNT_POINT=$(printf '%s\n' "$MOUNT_OUTPUT" | awk '/\/Volumes\// {for (i=3; i<=NF; i++) {printf (i==3 ? "%s" : " %s"), $i}; print ""}' | tail -n 1)
ditto "$MOUNT_POINT/Mindraw.app" "$APP_COPY"
hdiutil detach "$MOUNT_POINT"
```

验证步骤：

```bash
CAP="$HOME/Library/Application Support/com.mindraw.desktop/runtime/write-api.json"
open -n "$APP_COPY"
node scripts/mindraw-doctor.mjs --app "$APP_COPY" --min-version 1.2.4 --app-api-capability "$CAP" --pretty
```

临时 `/Applications` 验证框架：

```bash
INSTALLED='/Applications/Mindraw.app'
BACKUP_ROOT='/tmp/mindraw-md-edc-03-applications-backup-r1'
BACKUP="$BACKUP_ROOT/Mindraw.app"
LSREGISTER='/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister'
mkdir -p "$BACKUP_ROOT"
ditto "$INSTALLED" "$BACKUP"
rm -rf "$INSTALLED"
ditto "$APP_COPY" "$INSTALLED"
"$LSREGISTER" -f "$INSTALLED"
node scripts/mindraw-doctor.mjs --app "$INSTALLED" --min-version 1.2.4 --system-handlers --pretty
open -a "$INSTALLED"
open /tmp/mindraw-md-edc-03-installed-package-r1/minimal-empty.mindraw
open 'mindraw://localhost?documentId=<fixture-document-id>&elementId=shape_1'
```

清理 / 恢复命令：

```bash
osascript -e 'tell application id "com.mindraw.desktop" to quit' >/dev/null 2>&1 || true
rm -rf /Applications/Mindraw.app
ditto /tmp/mindraw-md-edc-03-applications-backup-r1/Mindraw.app /Applications/Mindraw.app
/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f /Applications/Mindraw.app
```

验证恢复：

```bash
pgrep -x Mindraw >/dev/null && echo running || echo absent
/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' /Applications/Mindraw.app/Contents/Info.plist
/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' /Applications/Mindraw.app/Contents/Info.plist
test -e "$HOME/Library/Application Support/com.mindraw.desktop/runtime/write-api.json" && echo capability_present || echo capability_absent
```

搜索关键词：`MD-EDC-03`、`APP_SIDE_NOT_ROOT_CAUSE`、`MINDRAW_OPEN_PACKAGE_API_REQUIRED`、`runtime/write-api.json`、`Build202607071930`、`open -a /Applications/Mindraw.app`。

## 未决问题 / 后续建议

- `M4C-EDC-03` 需要判断 capability 缺失时的 sidebar fallback：launch App、wait / retry、deep-link fallback 或用户可执行提示。
- PMO / QA 在 m4c/sidebar 修复或 runbook 调整后仍需执行 fresh machine / clean user 真实路径复验。
- 当前报告不是 QA PASS、用户验收或公开发布依据。