jpmschweitzerandClaude Opus 4.7
8074bf4201
`forkpty` calls `fork()` underneath. `fork()` in a multithreaded process is unsafe: only the calling thread survives in the child, but libc locks held by other threads remain "locked forever." With the multi-threaded Dart VM as parent, ~5% of spawns deadlocked in the child before `execve` (forensic probe: child stuck in S state with comm=`DartWorker`, master fd never sees POLLIN). `posix_spawn` uses `vfork` on glibc/musl/macOS, keeping the parent suspended until execve completes — no Dart code runs in the child. Pty pair built via the POSIX-standard `posix_openpt` / `grantpt` / `unlockpt` / `ptsname` sequence. Probed: zero hangs in 300 sequential spawns vs ~5% before. Behavior change: missing executable / missing workingDirectory now surface as a `PtyException` thrown by `NativePty.start` rather than a diagnostic written from the child to the slave PTY. Cleaner error path for callers. Side benefit: drops the `libutil.so.1` dynamic-library dependency. PTY now resolves entirely against libc via `DynamicLibrary.process()`. Splits the library-level `@Tags(['forkpty'])` on session_test.dart into a per-test tag, so the now-runnable-under-flutter-test cases contribute to coverage. `dart_test.yaml` declares the tag so the exclude-tags filters honor it. Drops the `retry: 2` workaround from the formerly-flaky registry test. D-5 amended. Trims session-introduced CHANGELOG entries that were over-verbose for the Keep-a-Changelog format. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Decisions, Questions, Rejected
This directory holds structured planning records that pql parses
into pql.db. Each record is a ### [DQR]-N: Title heading inside
a markdown file. Files live in three per-type subdirectories:
decisions/<domain>.md— confirmed design decisionsquestions/<domain>.md— open questions that may resolve into decisions or rejected proposalsrejected/<domain>.md— rejected proposals (kept for the audit trail)
The parser infers domain from the filename stem and record type from the parent subdirectory.
D-records that propose implementation work link to initiative-type
tickets via decision_ref. Run pql decisions show <id> --with-tickets to inspect implementation status.
Recommended domains
Start with this canonical set; create files as records land in each domain:
- architecture — structural commitments (storage, layering, languages, libraries)
- process — team workflow (commits, branches, releases, reviews)
- design — user-facing surface (UX, UI, public APIs)
- coding-conventions — team-internal code shape (style, lint, file layout)
- testing — quality strategy (coverage, layers, gates)
You might also want, project-permitting:
accessibility— if you ship user-facing softwaresecurity— if you handle user data or network surfaceslicensing— if you release open-source or commercialdocumentation— if user-docs are non-trivialdeployment— if shipping is non-trivialperformance— if you have perf budgets / SLOs
Decisions
- D-1: CLI-first, not MCP — architecture
- D-3: pql as supporter tool; clide wraps, never duplicates — architecture
- D-4: Ignore file strategy — architecture
- D-5: Dart core; sidecar dissolved;
ptycas pql-peer — architecture - D-6: CLI and event surface contract — architecture
- D-7: App root is bare
WidgetsApp— architecture - D-8: Feature-first folder layout — architecture
- D-9: Three-tier theme pipeline — architecture
- D-10: State management —
ChangeNotifier+ListenableBuilder— architecture - D-11: Panel manager is kernel; layout is data; three-column is a preset — architecture
- D-12: Kernel admission rule — mandatory shared singletons only — architecture
- D-13: Git hardcoded in kernel project-loader — architecture
- D-14: Two-tier disable — kernel locked, everything else extension-shaped — architecture
- D-15: Extension grain — container-level, multi-contribution — extensions
- D-16: Built-ins in Dart, third-party in sandboxed Lua — extensions
- D-17: Panels are extension-shaped from day one — extensions
- D-18: YAML for themes + manifests; JSON for i18n catalogs — extensions
- D-19: Lua runtime as
ptyc-peer supporter tool — extensions - D-20: A11y is a Tier-0 contract — accessibility
- D-21: i18n is a Tier-0 contract (fframe pattern + locale-fallback chain) — accessibility
- D-22: WCAG-AA contrast gate on bundled themes — accessibility
- D-23: Test pyramid — seven layers — testing
- D-24: Golden tests — primitives only, Alchemist + Ahem — testing
- D-25: Mocks — mocktail at IO, hand-rolled fakes for ChangeNotifiers — testing
- D-26: Web driver — raw Playwright + Flutter semantics — testing
- D-27: Startup regression gate — testing
- D-28: Test organisation — mirror
lib/intest/— testing - D-29: Pre-push gate — fast layer only — testing
- D-30: Tests are client-side only — testing
- D-31: Prefer-zero-deps, exact-pin — tooling
- D-32: CI — Gitea primary, Linux-only runners, not yet activated — tooling
- D-33: Golden-output ignore pattern —
coverage.*excludes output, not scripts — tooling - D-34: Q&D record system — process
- D-35: Kanban / waterfall, not Scrum — process
- D-36:
.claude/is committed project surface, managed through the IDE — process - D-37: Commit conventions per git-commit skill — process
- D-38: Changelog discipline — Keep a Changelog 1.1.0 — process
- D-39: Planning tooling lives in pql, not clide — process
- D-40: [SUPERSEDED] Python stopgap under
tools/scripts/plan— process - D-41: Claude panes — one primary per repo, tmux-backed — architecture
- D-42: Dependencies documented in
licenses.yaml— tooling - D-43: Design handoff — adopt token palettes, reject Material wrapper — architecture
- D-44: Four bundled themes — clide, midnight, paper, terminal — architecture
- D-45: Syntax highlighting tokens in the theme pipeline — architecture
- D-46: Core frame builtins vs shipped extensions boundary — extensions
- D-47: Interaction model — Claude-is-home layout — architecture
- D-48: Chrome budget — no tabs, no breadcrumbs, keyboard-first — architecture
- D-49: Editor mode — inline above Claude, viewer swap — architecture
- D-50: Context auto-behavior — right panel reacts to Claude — architecture
- D-51: Panel collapse — 12px spine with badge — architecture
- D-52: Focus mode — full-window takeover — architecture
- D-53: State persistence across sessions — architecture
- D-54: Keyboard map — canonical shortcuts — architecture
- D-55: Claude pane internal tabs for multi-session — architecture
- D-56: Dissolve daemon process; Flutter app hosts IPC server — architecture
- D-57: Frameless custom chrome with per-column 24px hats — architecture
- D-58: Format engines are adoptable dependencies — tooling
- D-59: Bundled git via dugite-native — tooling
- D-60: No network on default launch path — tooling
- D-61: Dependency vetting checklist — tooling
- D-62: Dependency removal process — tooling
- D-63: Vendored binary rebuild process — tooling
- D-64: No telemetry — architectural commitment — architecture
- D-65: License compatibility matrix — tooling
- D-66: Line coverage gate at 95%, ratcheted from current — testing
- D-67: Pql changelog files are committed alongside code — process
Open questions
- Q-1: Authorisation granularity on the IPC socket — architecture
- Q-2: Back-pressure on event streams — architecture
- Q-3: Event persistence + audit/undo — architecture
- Q-4:
.canvasschema compatibility with Obsidian — architecture - Q-5: IPC wire-format stability +
schema_version:— architecture - Q-6: Window chrome — native frame vs frameless custom — architecture
- Q-7: macOS app bundle signing / notarisation — architecture
- Q-8: Extension API shape — widgets, subcommands, both? — extensions
- Q-9: Lua runtime vendoring — extensions
- Q-10: Extension manifest
schema_version:— extensions - Q-11: Coverage gates — hard thresholds vs soft reporting — testing
- Q-12: Screen-reader automation (axe-core via Playwright) — testing
- Q-13: Web production-mode a11y — accessibility
- Q-14: i18n plurals / gender / date-format tooling — accessibility
- Q-15: Editor tab — full LSP vs tree-sitter-only highlight — process
- Q-16:
tree-sitter-dartgrammar maintenance — process - Q-17: Icon set growth — process
- Q-18: Theme hot-reload in release builds — process
- Q-19: (withdrawn) — process
- Q-20: Kernel DB service — namespaced SQL access? — process
- Q-21: Pql absorbs planning vs keeps separate — architecture
- Q-22: Ticket persistence strategy — architecture
- Q-23: SSH-remote development — run clide against a remote workspace — architecture
- Q-25: Body text face — mono everywhere vs Josefin Sans UI + mono code — architecture
- Q-26: Small screen layout (< 1000px) — architecture
- Q-27: Two-editor split — architecture
- Q-28: Terminal strip scope — shell only or logs/errors/tests — architecture
- Q-29: Branch picker location — architecture
- Q-30: Focus behavior when editor is dirty and viewer is peeked — architecture
- Q-31: XWayland fallback for frameless — proper Wayland protocol needed — architecture
Rejected
- R-2: Go sidecar — architecture
- R-3:
MaterialApproot — architecture - R-4: Flutter
intl+ ARB codegen for i18n — accessibility - R-5: Patrol test runner — testing
- R-6: Nerd-font glyph icons — process
- R-7:
CupertinoApproot — architecture - R-8: Riverpod / Provider / BLoC for state — architecture
- R-9: Port planning tooling into clide — process
- R-10: Python-script stopgap under
tooling/db/— process - R-11: Permanent stopgap — process
- R-12: MaterialApp wrapper from design handoff — architecture