fix(app): offer the session export repair only where the web does

Suppress the export-only repair for a legacy session.html with no recorded
evidence, narrow the identity check to the web's own, and keep the stricter
partial rule for an unverified complete status. Fix the analyzer findings,
add gating/legacy/Cupertino coverage, format, and correct the parity docs.
This commit is contained in:
2026-10-22 10:52:36 +01:00
parent d78712aa77
commit 776afcacea
8 changed files with 265 additions and 41 deletions
+2 -2
View File
@@ -34,12 +34,12 @@ or scratch servers only, never real operator sessions/runs/workflows.
| Retry/restart | Preview controls in the run detail | accepted new-run navigation, stale/refusal handling verified in the app |
| Human decisions | Preview waiting card/native prompt/exact accepted reply | attention/action URL entry; no production decision answered during tests |
| Run graph | Preview: Graph tab with legend, recorded-stage selection, canvas pan/zoom and an expanded view | live activity pulse |
| Timeline/recorded visit pane | Preview: selection opens the recorded facts with Input/Output/Artifacts/Session/Definition sections and exact absence wording | per-visit session-repair choices (separate row) |
| Timeline/recorded visit pane | Preview: selection opens the recorded facts with Input/Output/Artifacts/Session/Definition sections and exact absence wording | full per-visit session-repair choices (separate row); the export-only retry lives in Session |
| Changes/diffs | Preview via run detail | settled-run aggregate gate, recorded file/diff/close/back verified in the real app; per-visit capture entry and paging remain |
| Artifact groups | Preview: recorded groups in run detail, per-visit drill-down, turn documents (input/memory/output, session.html) in the run gallery | video/HTML preview remains external-only |
| Artifact preview | Preview: image + markdown/text in-app through the chat renderer, paging, honest unsupported/external/HTTP states | video and HTML remain external-only |
| Artifact actions | Preview: external Open, Copy link, download and native share carry the recorded name/MIME bytes; progress, cancel, HTTP failure and unsupported-share states | OS share/download on Android/iOS remain unverified until the final build |
| Session audit/export repair facts | Source: the visit Session section reports the recorded export state (complete, partial, missing, skipped, repair, or the server's verbatim unknown word), the recorded reason for a present export, and read-only repair attempt/option labels; `session.html` opens externally | publish a preview of these captures; the `repair_session_export` action and per-visit repair choices |
| Session audit/export repair facts | Source: the visit Session section reports the recorded export state (complete, partial, missing, skipped, repair, or the server's verbatim unknown word), the recorded reason for a present export, read-only repair attempt/option labels, and the export-only `repair_session_export` control for incomplete evidence; `session.html` opens externally | publish a preview of these captures, with rendered evidence of the control; full per-visit repair choices |
| Chat session management | Preview list + open session; shared create/rename/star/close/reopen with server-refreshed rows and full-width row refusals; local hide/undo and this device's read watermark (open rows only; a closed row never shows `New`) | dismissible web action-failed report (refusals stay under their row until the next accepted action), web `Open` badge and active/deep-linked read suppression, live `New` marks from pushed chat events, hide closing an already-open conversation, create dialog in the shell, editable create title (the web fixes `New chat`) |
| Chat history/live transport | Preview: `/chat` list and `/chat/:id` history, paging, live failure notice | run-detail-style reconnect verification in the real app, then composer integration |
| Chat message surfaces | Preview: formatted assistant markdown (safe links/headings/lists/tables/fences), user text exact, disclosures plain | exact attachments, unknown-part rendering beyond retained placeholders |
@@ -117,10 +117,7 @@ class _SessionExportRepairActionState extends State<SessionExportRepairAction> {
onPressed: enabled ? _send : null,
child: Text(label),
)
: TextButton(
onPressed: enabled ? _send : null,
child: Text(label),
);
: TextButton(onPressed: enabled ? _send : null, child: Text(label));
return Column(
key: sessionExportRepairKey,
crossAxisAlignment: CrossAxisAlignment.start,
@@ -108,6 +108,28 @@ String? detailVisitSessionIdentity(JsonMap step) {
return evidence == null ? null : recordedText(evidence['session_id']);
}
/// The session identity the web client requires before it offers an
/// export-only repair: the visit's own `session_id` or its original
/// `session_export.session_id`. A repair attempt's identity is not enough, and
/// neither is an identity read only from that repair, exactly as the web's
/// availability check does not widen the case.
String? detailVisitRepairIdentity(JsonMap step) {
final direct = recordedText(step['session_id']);
if (direct != null) return direct;
final original = step['session_export'];
return original is Map ? recordedText(original['session_id']) : null;
}
/// Whether the web audit pane offers the export-only repair for a document it
/// can open: only when recorded evidence is incomplete or truncated.
///
/// A legacy `session.html` selected by the no-evidence fallback has nothing to
/// compare and gets no control. A `complete` status without the server's
/// verified evidence stays [VisitSessionExportState.partial] here, so it keeps
/// the control; that is this client's deliberate, stricter rule.
bool visitSessionExportNeedsRepair(VisitSessionExport export) =>
export.truncated || (export.status != null && !export.isComplete);
/// The visit's recorded export document, or null when no recorded export name
/// is present in the inventory.
///
@@ -18,12 +18,13 @@ import 'run_detail_visit_session_state.dart';
/// recorded. Complete, partial, missing, skipped, repair and unrecognised
/// states each keep the server's own word and diagnostic; recorded repair
/// attempts and their open-option labels stay read-only. An export whose
/// recorded evidence is not complete offers the web client's export-only
/// repair, which sends that exact visit's recorded sequence and keeps this
/// recorded state until the server replies. The open goes through the landed
/// safe-link helper: the recorded url is resolved by [resolveArtifactUrl] and
/// passed to [openArtifactExternally] without being fetched, rewritten or
/// previewed. A refusal is reported.
/// recorded evidence is incomplete or truncated offers the web client's
/// export-only repair, which sends that exact visit's recorded sequence and
/// keeps this recorded state until the server replies; a legacy `session.html`
/// with no recorded evidence offers no control, exactly as the web does. The
/// open goes through the landed safe-link helper: the recorded url is resolved
/// by [resolveArtifactUrl] and passed to [openArtifactExternally] without being
/// fetched, rewritten or previewed. A refusal is reported.
class RunVisitSession extends StatefulWidget {
const RunVisitSession({
super.key,
@@ -97,7 +98,7 @@ class _RunVisitSessionState extends State<RunVisitSession> {
const Text(visitSessionEndpointMissing)
else
_openButton(export.artifact, resolved),
if (repair != null) repair,
?repair,
if (_status != null)
Padding(
padding: const EdgeInsets.only(top: 8),
@@ -146,13 +147,16 @@ class _RunVisitSessionState extends State<RunVisitSession> {
/// The export-only repair option: offered only for a visit whose recorded
/// session identity and sequence can be read again, and whose recorded export
/// is not already verified complete. The visit's own recorded sequence is
/// sent, never a guessed one.
/// evidence is incomplete or truncated (or which has no openable document at
/// all). A legacy `session.html` chosen only by the no-evidence fallback has
/// no evidence to repair and keeps the web's absence of the control. The
/// visit's own recorded sequence is sent, never a guessed one.
Widget? _repairAction(VisitSessionState session, int sequence) {
final runId = recordedCount(widget.run['id']);
if (runId < 1 || sequence < 1 || session.sessionId == null) return null;
if (runId < 1 || sequence < 1) return null;
if (detailVisitRepairIdentity(widget.step) == null) return null;
final export = session.export;
if (export != null && export.isComplete) return null;
if (export != null && !visitSessionExportNeedsRepair(export)) return null;
final status = recordedText(widget.step['status']);
final runStatus = recordedText(widget.run['status']);
final pending = recordedCount(widget.run['export_pending_sequence']);
+5 -3
View File
@@ -21,7 +21,8 @@ Completeness is not inferred: it requires `status == "complete"`, positive
`messages` and `html_bytes`, no truncation and no diagnostic. A complete status
without that evidence is `partial`; a legacy `session.html` with no evidence is
`unknown`, never `complete`. Repairs are shown even when the main export is
complete. No `repair_session_export` request is sent or advertised.
complete. This slice sent no request; the export-only `repair_session_export`
control landed later (see `notes/session-export-repair.md`).
## Review fixes (visit 2)
@@ -143,8 +144,9 @@ narrow-layout constraint recorded in `notes/R4-visit.md`, not new to this change
remains portable (Material/Cupertino theme roles and plain text layout only).
- No authenticated server or production run was touched; fixtures only. The
preview is not published to 8096.
- `repair_session_export` remains unwired, and the repair-option label remains
inert text by design.
- The export-only `repair_session_export` control landed later and is described
in `notes/session-export-repair.md`; full per-visit repair choices remain
unwired, and the repair-option label remains inert text by design.
- Artifact matching still selects by recorded name only, as it did before this
change; web additionally filters repairs by session/backend/directory and
checks `size_bytes == html_bytes`. Inherited, not changed here.
+79
View File
@@ -0,0 +1,79 @@
# Visit Session export-only repair
## Delivered
The Timeline visit pane's Session section offers the web client's export-only
session repair for that exact visit:
- **Control** — `Retry export only` in a native `TextButton` (Material) or
`CupertinoButton` (Cupertino); `Exporting…` while the request is pending.
Disabled while the visit/run is active or a request is pending, so one
choice sends one request.
- **Request** — `RunsRepository.repairSessionExport` sends
`repair_session_export` with exactly `run_id` and the visit's recorded
`export_sequence` and requires `run_detail` in the reply, matching
`web/src/repository.js` and the Go protocol. No choice id is invented: the
visit's own recorded sequence is the choice.
- **Reply** — the accepted run detail is folded through
`RunsController.acceptRunDetail`, so the pane re-reads the recorded
repair/export facts. Nothing is mutated optimistically.
- **Refusal** — the server's reason is shown verbatim beside the unchanged
recorded state; the control remains available and no success word appears.
- **Scope of state** — in-flight/refusal state is per `run:sequence`;
changing visits clears it and a late reply for another visit is ignored.
## Availability rule (recorded decision)
The web inserts the control in two places of `auditSession`
(`web/src/views/runDetail.js:361-388`): when there is no openable artifact at
all, and when recorded evidence exists with a non-complete status or a
truncated document. The app now mirrors that:
- no document at all plus the web's identity (`step.session_id` or
`step.session_export.session_id`) and a positive sequence → offered;
- present document → offered only when
`visitSessionExportNeedsRepair(export)` is true (truncated, or a recorded
status that is not verified complete);
- a legacy `session.html` selected only by the no-evidence fallback → **not**
offered, matching the web (nothing to compare, and the server's ownership
join would likely refuse it).
Deliberate difference from the web, preserved: this client treats a recorded
`complete` status without the server's positive `messages`/`html_bytes`,
untruncated and diagnostic-free evidence as `partial`, so that document keeps
the control. The app does not widen identity to an id read only from repair
evidence; the web does not either.
## Review fixes (visit 2)
- Suppressed the control for the legacy no-evidence `session.html` and added
Material/Cupertino regression coverage.
- Fixed the two analyzer findings: `?repair,` null-aware element and a private
test helper.
- `dart format` applied to the changed files.
- Updated `PARITY.md` and `notes/R4-session-export.md`, which still said the
command was unwired.
- Added coverage for active/`waiting` gating, complete-export suppression,
visit-change state clearing, the Cupertino control and "no other request".
## Known nonblocking gaps
- In-flight state is widget-local: leaving the Session section and returning
before the reply allows a second tap. The web keeps a page-level `run:seq`
pending set. The normal live path still converges through the server's
`session_export_updated` event and the scheduled `get_run`.
- A reply completing after the pane unmounts is dropped; the same server event
re-reads the run.
- Artifact matching is by name only, ignoring `size_bytes == html_bytes` and
repair session/backend/directory filters (documented in
`notes/R4-session-export.md`). Inherited.
- Full per-visit repair choices remain unwired.
## Verification
- `flutter analyze` — No issues found.
- `flutter test test/features/runs` — 212 passed.
- `flutter test` — 1335 passed.
- `flutter build web` — built.
- No browser interaction/capture, Android/iOS build or device check was run.
Mobile remains unverified.
@@ -19,6 +19,8 @@ void main() {
expect(find.text('sess-1'), findsOneWidget);
expect(find.text('Open session.html'), findsOneWidget);
// No recorded export evidence, so the web offers no export-only repair.
expect(find.text('Retry export only'), findsNothing);
expect(
find.textContaining('not available in the artifact inventory'),
findsNothing,
@@ -85,6 +87,8 @@ void main() {
findsOneWidget,
);
expect(find.textContaining('Open '), findsNothing);
// No openable document at all is the web's other repair branch.
expect(find.text('Retry export only'), findsOneWidget);
step['session_export'] = <String, dynamic>{
'html': 'session.html',
@@ -1,5 +1,6 @@
import 'dart:async';
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/core/api_gateway.dart';
@@ -8,8 +9,7 @@ import 'package:pipelines_app/features/runs/ui/run_detail_visit_session.dart';
import 'run_detail_visit_support.dart';
typedef _RepairHandler =
Future<JsonMap> Function(String type, JsonMap fields);
typedef _RepairHandler = Future<JsonMap> Function(String type, JsonMap fields);
class _RepairGateway implements ApiGateway {
_RepairGateway(this.handler);
@@ -79,42 +79,57 @@ class _SessionHostState extends State<_SessionHost> {
late JsonMap _run = widget.run;
@override
Widget build(BuildContext context) => Scaffold(
body: RunVisitSession(
run: _run,
step: firstVisitStep(_run),
gateway: widget.gateway,
onRunChanged: (detail) => setState(() => _run = detail),
configuredEndpoint: 'ws://example.test/connect',
),
void didUpdateWidget(covariant _SessionHost oldWidget) {
super.didUpdateWidget(oldWidget);
// A test that swaps the recorded run must show the new visit, exactly as
// the detail does when the operator selects another one.
if (!identical(widget.run, oldWidget.run)) _run = widget.run;
}
@override
Widget build(BuildContext context) => RunVisitSession(
run: _run,
step: firstVisitStep(_run),
gateway: widget.gateway,
onRunChanged: (detail) => setState(() => _run = detail),
configuredEndpoint: 'ws://example.test/connect',
);
}
Future<void> pumpSession(
Future<void> _pumpSession(
WidgetTester tester,
_RepairGateway gateway, {
JsonMap? run,
}) => tester.pumpWidget(
MaterialApp(
home: _SessionHost(run: run ?? partialRun(), gateway: gateway),
),
bool cupertino = false,
}) {
final host = _SessionHost(run: run ?? partialRun(), gateway: gateway);
return tester.pumpWidget(
cupertino
? CupertinoApp(
home: CupertinoPageScaffold(child: SafeArea(child: host)),
)
: MaterialApp(home: Scaffold(body: host)),
);
}
TextButton _materialButton(WidgetTester tester) => tester.widget<TextButton>(
find.widgetWithText(TextButton, 'Retry export only'),
);
void main() {
testWidgets('sends the recorded run and visit exactly once', (tester) async {
final reply = Completer<JsonMap>();
final gateway = _RepairGateway((_, _) => reply.future);
await pumpSession(tester, gateway);
await _pumpSession(tester, gateway);
expect(find.text('Retry export only'), findsOneWidget);
await tester.tap(find.text('Retry export only'));
await tester.pump();
expect(gateway.repairs, hasLength(1));
expect(gateway.repairs.single.fields, {
'run_id': 77,
'export_sequence': 1,
});
expect(gateway.repairs.single.fields, {'run_id': 77, 'export_sequence': 1});
// Nothing but the one repair request is sent.
expect(gateway.calls.map((call) => call.type), ['repair_session_export']);
// The recorded export state is kept until the server replies.
expect(find.text('partial'), findsOneWidget);
expect(find.text('complete'), findsNothing);
@@ -140,7 +155,7 @@ void main() {
final gateway = _RepairGateway(
(_, _) => Future<JsonMap>.error(StateError('The session is gone.')),
);
await pumpSession(tester, gateway);
await _pumpSession(tester, gateway);
await tester.tap(find.text('Retry export only'));
await tester.pumpAndSettle();
@@ -152,4 +167,105 @@ void main() {
// The option is still available: a refusal is not a success.
expect(find.text('Retry export only'), findsOneWidget);
});
testWidgets('a legacy session.html with no recorded evidence keeps no '
'control', (tester) async {
final gateway = _RepairGateway(
(_, _) => Future<JsonMap>.error(StateError('unexpected')),
);
final run = partialRun();
firstVisitStep(run).remove('session_export');
await _pumpSession(tester, gateway, run: run);
// The document still opens, but there is no evidence to repair.
expect(find.text('Open session.html'), findsOneWidget);
expect(find.text('Retry export only'), findsNothing);
expect(gateway.calls, isEmpty);
});
testWidgets('a verified complete export offers no repair', (tester) async {
final gateway = _RepairGateway(
(_, _) => Future<JsonMap>.error(StateError('unexpected')),
);
await _pumpSession(tester, gateway, run: visitRunFixture());
expect(find.text('complete'), findsOneWidget);
expect(find.text('Retry export only'), findsNothing);
});
testWidgets('the control is disabled while the visit or run is active', (
tester,
) async {
final gateway = _RepairGateway(
(_, _) => Future<JsonMap>.error(StateError('unexpected')),
);
final active = partialRun();
firstVisitStep(active)['agent_active'] = true;
await _pumpSession(tester, gateway, run: active);
expect(find.text('Retry export only'), findsOneWidget);
expect(_materialButton(tester).onPressed, isNull);
final waiting = partialRun();
waiting['status'] = 'waiting';
waiting['export_pending_sequence'] = 2;
await _pumpSession(tester, gateway, run: waiting);
expect(_materialButton(tester).onPressed, isNull);
// The same wait allows the repair when this visit's export is the pending
// one, exactly as the web client's availability check does.
waiting['export_pending_sequence'] = 1;
await _pumpSession(tester, gateway, run: waiting);
expect(_materialButton(tester).onPressed, isNotNull);
});
testWidgets('changing visits clears a pending repair and its reply', (
tester,
) async {
final first = Completer<JsonMap>();
final second = Completer<JsonMap>();
final gateway = _RepairGateway(
(_, fields) =>
fields['export_sequence'] == 1 ? first.future : second.future,
);
await _pumpSession(tester, gateway);
await tester.tap(find.text('Retry export only'));
await tester.pump();
expect(find.text('Exporting…'), findsOneWidget);
final next = partialRun();
firstVisitStep(next)['sequence'] = 2;
await _pumpSession(tester, gateway, run: next);
expect(find.text('Retry export only'), findsOneWidget);
expect(find.text('Exporting…'), findsNothing);
await tester.tap(find.text('Retry export only'));
await tester.pump();
expect(gateway.repairs.map((call) => call.fields['export_sequence']), [
1,
2,
]);
// The first visit's late reply is not folded into the second visit.
first.complete({'run_detail': repairedRun()});
await tester.pump();
expect(find.text('repair'), findsNothing);
expect(find.text('partial'), findsOneWidget);
});
testWidgets('the Cupertino host uses a native Cupertino button', (
tester,
) async {
final gateway = _RepairGateway(
(_, _) => Future<JsonMap>.error(StateError('unexpected')),
);
await _pumpSession(tester, gateway, cupertino: true);
expect(
find.widgetWithText(CupertinoButton, 'Retry export only'),
findsOneWidget,
);
expect(find.widgetWithText(TextButton, 'Retry export only'), findsNothing);
});
}