@capagents/forgeqe 2.3.3 → 2.3.5

package/docs/user-guide.html

@@ -389,7 +389,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 <div class="area"><a class="area-name" href="#area-setup"><span class="mono">Setup</span></a><ul class="tiles"><li><a class="tile" href="#cap-test-apps"><b>Test environments and their apps</b><span>Place an order in the shop, then check its invoice in Billing, in UAT</span></a></li><li><a class="tile" href="#cap-generated-code"><b>What ForgeQE wrote</b><span>How much of the code ForgeQE wrote is still there?</span></a></li><li><a class="tile" href="#cap-forgeqe-commands"><b>Every forgeqe command from the shell</b><span>Show me the context budget</span></a></li><li><a class="tile" href="#cap-setup-help"><b>Setup, skills, and documentation</b><span>What can you do?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-desktop"><span class="mono">Desktop</span></a><ul class="tiles"><li><a class="tile" href="#cap-desktop-apps"><b>Automate Windows desktop apps</b><span>Create an invoice for Contoso in the Billing app and save it as a test</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-mobile"><span class="mono">Mobile</span></a><ul class="tiles"><li><a class="tile" href="#cap-mobile-apps"><b>Automate Android and iOS apps</b><span>Sign in to the courier app and accept the first delivery, and save it as a test</span></a></li></ul></div>
-<div class="area"><a class="area-name" href="#area-operations"><span class="mono">Operations</span></a><ul class="tiles"><li><a class="tile" href="#cap-containers"><b>Services, mocks, workspace and browser in Docker or Podman</b><span>Start the database and the queue in Docker</span></a></li><li><a class="tile" href="#cap-monitoring"><b>Scheduled monitoring with alerts</b><span>Check the login flow every 15 minutes and alert Teams</span></a></li><li><a class="tile" href="#cap-notifications"><b>Teams and email notifications</b><span>Post the results to the QA channel</span></a></li><li><a class="tile" href="#cap-pipelines"><b>CI pipelines</b><span>Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-operations"><span class="mono">Operations</span></a><ul class="tiles"><li><a class="tile" href="#cap-containers"><b>Services, mocks, workspace and browser in Docker or Podman</b><span>Start the database and the queue in Docker</span></a></li><li><a class="tile" href="#cap-monitoring"><b>Scheduled monitoring with alerts</b><span>Check the login flow every 15 minutes and alert Teams</span></a></li><li><a class="tile" href="#cap-jobs"><b>Background jobs on a schedule</b><span>Run the release-2.3 pack every weekday at 2am in the background</span></a></li><li><a class="tile" href="#cap-notifications"><b>Teams and email notifications</b><span>Post the results to the QA channel</span></a></li><li><a class="tile" href="#cap-pipelines"><b>CI pipelines</b><span>Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-data"><span class="mono">Data</span></a><ul class="tiles"><li><a class="tile" href="#cap-databases"><b>Ask a database in plain language</b><span>Which customers in India have paid orders? Ask the orders database</span></a></li><li><a class="tile" href="#cap-test-data"><b>Test data on demand</b><span>Generate test data: 20 customers with 1 to 3 orders each in the shop database</span></a></li><li><a class="tile" href="#cap-data-flows"><b>Data flows between systems</b><span>Check that customers from the digital database reach the CRM correctly</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-automated-tests"><span class="mono">Automated tests</span></a><ul class="tiles"><li><a class="tile" href="#cap-write-tests"><b>Turn a passed run into an automated test</b><span>Write a Playwright test for that run in ../app</span></a></li><li><a class="tile" href="#cap-heal-tests"><b>Heal failing tests</b><span>Heal the failing tests in ../app</span></a></li><li><a class="tile" href="#cap-find-run-tests"><b>Find and run existing tests</b><span>Run the checkout tests</span></a></li><li><a class="tile" href="#cap-regression-packs"><b>Regression packs for a release</b><span>Build a regression pack for sprint 12 and run it on TestMu</span></a></li><li><a class="tile" href="#cap-flaky-tests"><b>Flaky test detection and quarantine</b><span>Which tests are flaky?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-pull-requests"><span class="mono">Pull requests</span></a><ul class="tiles"><li><a class="tile" href="#cap-pr-review"><b>Review pull requests</b><span>Review PR 42 and focus on error handling</span></a></li><li><a class="tile" href="#cap-pr-impact"><b>Pull request impact and test selection</b><span>What does PR 42 impact?</span></a></li></ul></div>
@@ -616,6 +616,7 @@ bun src/index.ts init --global --profile azure-gpt4o
 <tr><td><code>Model for agent: main, because copilot failed its live check …</code></td><td>ForgeQE used your other model because Copilot did not answer; the message ends with the fix.</td></tr>
 <tr><td>The model is refused, or not found</td><td>The seat's plan or your organization's Copilot policies do not allow that model: pick one the sign-in listed, or ask a Copilot admin to enable it.</td></tr>
 <tr><td><code>GitHub Copilot runs through the ForgeQE engine, which is not set up</code> (or <code>could not be set up (…)</code>)</td><td>Run <code>forgeqe setup</code>; the reason in brackets says what failed.</td></tr>
+<tr><td>Copilot is slow, or a run waits on it (&quot;Starting the browser…&quot;, &quot;working out the first step…&quot;)</td><td><code>~/.forgeqe/logs/copilot-gateway.log</code> has a line for each Copilot request: when it started, Copilot's session, when each turn ended, and how long it took. It never holds prompts, replies or tokens. A turn that ends without Copilot saying it is idle (a known Copilot SDK issue) is answered 5 seconds later instead of after the 5-minute limit, and a session the run no longer needs (Stop, an error) is stopped.</td></tr>
 <tr><td><code>CERTIFICATE_VERIFY_FAILED</code> while downloading Copilot's runtime</td><td>Your network inspects HTTPS. Update ForgeQE and run <code>forgeqe setup</code>, then sign in again: it uses the certificates your computer trusts (see <a href="../HOW_TO_USE.md#company-networks">Company networks</a>). If it still fails, run <code>forgeqe doctor</code> and send its output to IT.</td></tr>
 </tbody>
 </table></div>
@@ -3237,6 +3238,62 @@ forgeqe monitor --once                         # one round, then exit (cron, sch
 </section>
 </div>
 </article>
+<article class="spec feat" id="cap-jobs">
+<div class="hd"><span class="mono">Operations</span><h3>Background jobs on a schedule</h3></div>
+<p class="ds">Runs ForgeQE commands (suites, monitor rounds, regression packs, healing, pull-request tests, browser goals) on a schedule or once in the jobs service, apart from the conversation and after it closes, and watches an existing GitHub Actions or Azure DevOps pipeline (read-only). A failed pipeline run or pack run is investigated: the healing agent works on each failure on a local branch of its own (a fix for review, or an app bug), never pushing. Says how each job goes when asked, shows runs as they end, and sends failures, recoveries and findings to Teams or email.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Run the release-2.3 pack every weekday at 2am in the background</li><li>Watch the pipeline in the background and investigate failures</li><li>How are my jobs doing?</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need opt">Optional</span><span>A notification channel: notify.channels in forgeqe.yaml, each a Teams Workflows webhook (in an environment variable) or email</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>jobs</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-the-jobs-service-scheduled-and-long-jobs-apart-from-the-shell">
+<h4>The jobs service: scheduled and long jobs apart from the shell</h4>
+<div class="prose"><p><code>forgeqe jobs</code> runs ForgeQE commands on a schedule, or once, in a service of their own, so they keep going while you work on something else in the shell, or with the shell closed. Each run is its own <code>forgeqe</code> process with its own output and session log; you ask how a job is going at any time, and its failures and recoveries go to Teams.</p>
+<pre><code class="language-bash">forgeqe jobs add nightly-pack --cron &quot;0 2 * * 1-5&quot; -- pack run release-2.3   # weekdays at 02:00, this machine's time
+forgeqe jobs add smoke --every 30m -- suite checks/smoke.yaml
+forgeqe jobs add heal-login --now -- heal --focus login                     # once, now
+forgeqe jobs                       # every job: running or how its last run ended, and when it runs next
+forgeqe jobs status nightly-pack   # its last runs, and the last lines of the latest
+forgeqe jobs logs nightly-pack --tail 100
+forgeqe jobs run nightly-pack      # run it now as well
+forgeqe jobs stop nightly-pack     # stop the run that is going
+forgeqe jobs disable|enable|remove nightly-pack
+forgeqe jobs shutdown              # stop the service; scheduled jobs wait until it starts again
+</code></pre>
+<ul>
+<li><strong>What a job runs.</strong> One ForgeQE command: <code>suite</code>, <code>monitor</code>, <code>run</code>, <code>heal</code>, <code>pr-tests</code>, <code>pack run</code>, <code>pack triage</code> or <code>pipeline watch</code>, with its arguments after <code>--</code>. Nobody is there to answer a question while a job runs, so a <code>run</code> job is a browser run of the goal (<code>--direct</code>), and a <code>pack run</code> job carries <code>--yes</code>: adding the job is your approval, and the command you agree to shows it. It runs with the project's own <code>forgeqe.yaml</code>, model profile and approvals: a job cannot set <code>--config</code>, <code>--profile</code> or <code>--yes</code>, and nothing else is started (no shell, no other program). A <code>monitor</code> job runs one round each time it is due (<code>--once</code>), on the job's schedule; it sends its own <code>monitor.alerts</code>, so its job is quiet unless you add it with notices on.</li>
+<li><strong>When.</strong> <code>--every 15m</code> (at least 1m), <code>--cron &quot;0 2 * * 1-5&quot;</code> (minute hour day month weekday, local time), or neither: it runs when asked, and <code>add</code> starts it at once. <code>--now</code> also runs a scheduled job straight away. A run missed while the service was down starts once when it is back. When several are due, the one that has waited longest goes first.</li>
+<li><strong>How many.</strong> <code>jobs.parallel</code> in <code>forgeqe.yaml</code> (default 2) runs at once over all jobs, and never two runs of one job. A run past <code>--timeout</code> (default 6h, at most 24h) is stopped and marked timed out.</li>
+<li><strong>The service.</strong> <code>forgeqe jobs add</code> and <code>forgeqe jobs run</code> start it when it is not running, as a process of its own that outlives the command and the shell; <code>forgeqe jobs serve</code> runs it in the foreground (for a container or a system service). It is one per project, on this machine, until you stop it or the machine restarts. It listens on 127.0.0.1 only, with a random token kept in your own ForgeQE folder (<code>~/.forgeqe/jobs/</code>, readable by your user only, never in the project, which others may read), and refuses requests from web pages. A second service for the same project is refused. <code>.forgeqe/jobs/</code> and <code>.forgeqe/pipelines/</code> get their own <code>.gitignore</code>, so runs and logs are never committed.</li>
+<li><strong>Files.</strong> <code>.forgeqe/jobs/&lt;job&gt;/job.json</code> and, for each of its last 50 runs, <code>runs/&lt;run&gt;/run.json</code> and <code>output.log</code>; <code>.forgeqe/jobs/events.jsonl</code> lists what happened; <code>.forgeqe/jobs/service.log</code> is the service's own output. A run that was going when the service stopped is marked interrupted.</li>
+<li><strong>Watching a CI pipeline.</strong> <code>forgeqe jobs add ci --every 10m -- pipeline watch --github org/app --workflow ci.yml --branch main</code> (or <code>--ado-project Shop --pipeline 12</code>) looks at the pipeline's latest completed run each time, read-only: it starts, re-runs and changes nothing. A new failed run is triaged like a pack's (the JUnit or TRX files in its artifacts on GitHub, the Test Runs API on Azure DevOps; without results, the job and step that failed), in <code>.forgeqe/reports/pipelines/</code>. The job fails while the latest run is failed, so the team hears once when the pipeline breaks and once when it is green again; a cancelled run changes nothing. <code>forgeqe pipeline watch …</code> on its own does one look. GitHub needs the <code>gh</code> CLI signed in; Azure DevOps the same sign-in as the rest of ForgeQE.</li>
+<li><strong>Investigating failures.</strong> When a <code>pipeline watch</code> or <code>pack run</code> job fails, the failures that healing can decide (an element not found, an expected value that does not hold; not the environment, flaky tests or broken test code, and nothing while the environment is down) are investigated, at most 3 a run, <code>jobs.parallel</code> at once. Each goes to the healing agent in a git worktree of its own, on a new local branch <code>forgeqe/investigate/&lt;test&gt;-&lt;time&gt;-&lt;n&gt;</code>, from the commit the failing run tested when this clone has it (fetched when it can be, else <code>HEAD</code>, which the finding says). The agent re-runs the flow in the browser: when the flow works it heals the test, and the fix is committed on that branch for you to review; when the browser fails at the same step it is an app bug, and no branch is kept. Your checkout, its branch and its files are never touched; nothing is pushed or merged; the worktree is removed at the end. <code>node_modules</code>, <code>.venv</code> and <code>venv</code> from your checkout are linked into the worktree so the tests can run, and never committed. The failure is told at once (<code>job_failed</code>), the findings when they are in (<code>job_investigated</code>); <code>forgeqe jobs status</code> lists them, <code>.forgeqe/jobs/&lt;job&gt;/runs/&lt;run&gt;/investigations.json</code> and <code>investigate.log</code> have the detail, and <code>forgeqe investigate &lt;run folder&gt;</code> runs an investigation by hand. <code>--no-investigate</code> turns it off for a job.</li>
+<li><strong>From the shell.</strong> Ask ForgeQE's agent: &quot;run the release-2.3 pack every weekday at 2am in the background&quot; makes it propose the job, and ForgeQE asks you to agree to its exact command and schedule before adding it (<strong>Add the job</strong> / <strong>Don't add it</strong>). You keep working; when a job's run ends, a line says so in the conversation (&quot;Job nightly-pack failed: …&quot;), and &quot;how are my jobs?&quot; or &quot;show the end of the nightly-pack log&quot; get answers from the service. The agent adds a job only when you ask for one, and never one that runs anything but the commands above.</li>
+<li><strong>Notices.</strong> With <code>notify:</code> channels set up (section 17), a job that fails sends <code>job_failed</code> once (not every run while it keeps failing), <code>job_recovered</code> when it passes again, and a job that runs only when asked sends <code>job_done</code> when it ends. <code>--no-notify</code> keeps a job quiet.</li>
+</ul>
+<pre><code class="language-yaml">jobs:
+  parallel: 2
+</code></pre>
+<p><strong>On company machines.</strong> Nothing here needs administrator rights:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>What</th><th>Needs</th></tr>
+</thead>
+<tbody>
+<tr><td>The jobs service</td><td>Runs as you, in your project and your ForgeQE folder. It listens on 127.0.0.1 only, so no firewall rule is needed. Endpoint security may see a background <code>bun</code> process: it is ForgeQE's own (in its install folder), which IT can allow. Jobs pause while the machine sleeps or is off and a missed run starts once when it is back; for always-on jobs, run <code>forgeqe jobs serve</code> on a VM or build agent under its service manager (systemd, a Windows Task Scheduler task &quot;at log on&quot;, which needs no administrator, or a container).</td></tr>
+<tr><td><code>pipeline watch</code> on GitHub</td><td>The <code>gh</code> CLI signed in (<code>gh auth login</code>) with read access to the repository's Actions. A fine-grained token needs Actions: read and Contents: read; with SAML single sign-on, authorize the token for the organization. GitHub Enterprise Server: <code>--github host/owner/repo</code> and <code>gh auth login --hostname host</code>.</td></tr>
+<tr><td><code>pipeline watch</code> on Azure DevOps</td><td>The Azure DevOps sign-in ForgeQE already uses (<code>forgeqe auth login azure_devops</code>, or a token in <code>ADO_PAT</code>) with Build: read and Test Management: read. Azure DevOps Server works through its collection URL.</td></tr>
+<tr><td>Investigating failures</td><td>git, read access to fetch the failing commit, the tests' dependencies installed in your checkout, and a model: a key-based profile, or GitHub Copilot where the organization's policy allows Copilot CLI and the SDK. Branches are local; nothing is pushed.</td></tr>
+<tr><td>Teams notices</td><td>A Workflows webhook (&quot;post to a channel when a webhook request is received&quot;), or an incoming webhook where the tenant still allows them; where neither is allowed, email.</td></tr>
+<tr><td>Proxy and inspected HTTPS</td><td>The same as the rest of ForgeQE (section &quot;Company networks&quot;); <code>gh</code> uses <code>HTTPS_PROXY</code>. <code>forgeqe doctor</code> checks the machine and the network.</td></tr>
+</tbody>
+</table></div>
+<p>On Windows, the dependency folders are linked into worktrees as junctions (no administrator or developer mode needed), a stopped run ends at once rather than being asked to finish, and the token file is protected by your user profile's permissions.</p>
+</div>
+</section>
+</div>
+</article>
 <article class="spec feat" id="cap-notifications">
 <div class="hd"><span class="mono">Operations</span><h3>Teams and email notifications</h3></div>
 <p class="ds">Tells the team in Microsoft Teams channels or by email when a suite fails or passes, when a release readiness verdict is in, and when the domain evaluation falls below its gate, with the failing cases, their bugs, and links to the report and the CI build. Each channel picks its events; the agent also posts a summary to a channel when asked.</p>
@@ -3272,9 +3329,13 @@ forgeqe monitor --once                         # one round, then exit (cron, sch
 <tr><td><code>suite_passed</code></td><td>Every case passed</td><td>The count, how long it took, where it ran</td></tr>
 <tr><td><code>release</code></td><td>A release readiness verdict</td><td>GO, GO WITH RISKS, or NO-GO, the counts, every blocker and risk, and the wiki page when published</td></tr>
 <tr><td><code>eval_failed</code></td><td><code>forgeqe eval domain --min</code> falls below its gate</td><td>Coverage for each variant and invented ids</td></tr>
+<tr><td><code>job_failed</code></td><td>A job of the jobs service fails or runs out of time, after passing or for the first time (not again while it keeps failing)</td><td>The job, its command and schedule, how long it ran, its last lines of output, and where its output is</td></tr>
+<tr><td><code>job_recovered</code></td><td>A job passes again after failing</td><td>The same, for the run that passed</td></tr>
+<tr><td><code>job_done</code></td><td>A job that runs only when asked ends</td><td>The same, whether it passed or failed</td></tr>
+<tr><td><code>job_investigated</code></td><td>The investigation of a job's failed run is done</td><td>Each failure: a test out of date with its fix on a branch, an app bug, or not decided, with the agent's reasons</td></tr>
 </tbody>
 </table></div>
-<p>A channel without <code>on</code> gets <code>suite_failed</code>, <code>release</code>, and <code>eval_failed</code>. Email adds the failure screenshots. A stopped suite is not announced. Monitoring keeps its own <code>monitor.alerts</code>, with the same cards.</p>
+<p>A channel without <code>on</code> gets <code>suite_failed</code>, <code>release</code>, <code>eval_failed</code>, <code>job_failed</code>, <code>job_recovered</code>, and <code>job_investigated</code>. Email adds the failure screenshots. A stopped suite is not announced. Monitoring keeps its own <code>monitor.alerts</code>, with the same cards.</p>
 <p>Events are sent from runs nobody is watching: <code>forgeqe suite</code> in a pipeline or on a schedule, <code>forgeqe run</code>, and the MCP server. In the shell, where people try things out, nothing is sent on its own; ask instead (&quot;post the results to the QA channel&quot;, &quot;tell the release channel the verdict&quot;), and ForgeQE's agent posts a card with <code>notify</code>.</p>
 <p>Links: with <code>report_url</code>, cards open the report where the reports folder is published. In Azure Pipelines and GitHub Actions they also open the build, where the report is an artifact. Without either, the card names the report's path.</p>
 <p><strong>Setting up a Teams channel:</strong></p>

package/forgeqe.example.yaml

@@ -133,7 +133,7 @@ prompts:
 # industry would, and add each regulation's obligations a feature touches. Your applicable controls, with their ids,
 # go in .forgeqe/knowledge/compliance.md; agents cite only ids listed there.
 # Teams and email notifications for the team: each channel picks its events (suite_failed, suite_passed, release,
-# eval_failed). The Teams webhook URL is a secret: keep it in the environment, never here. See HOW_TO_USE.md section 17.
+# eval_failed, job_failed, job_recovered, job_done). The Teams webhook URL is a secret: keep it in the environment, never here. See HOW_TO_USE.md section 17.
 # notify:
 #   report_url: https://reports.example.com/forgeqe   # where .forgeqe/reports is published; cards link each report
 #   channels:
@@ -360,3 +360,8 @@ suite:
 #       password_env: SMTP_PASSWORD
 #       # from: ForgeQE <qa-bot@example.com>   # default: the username
 #       to: [qa-team@example.com]
+
+# forgeqe jobs: ForgeQE commands on a schedule or once, in a service apart from the shell (HOW_TO_USE.md, "The jobs
+# service"). Jobs are added with forgeqe jobs add; this sets how many runs go at once over all jobs.
+# jobs:
+#   parallel: 2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "2.3.3",
+  "version": "2.3.5",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/prompts/brain.md

@@ -356,6 +356,15 @@ For REST, GraphQL, SOAP, and gRPC:
 - For monitoring that continues after this session, you SHOULD set up forgeqe monitor on a computer that is always on, or forgeqe monitor --once from cron or a scheduled pipeline.
 - That pipeline MUST keep .forgeqe/reports/monitor/state.json between runs (a cache), so that alerts start only on changes.
 
+### Background jobs
+- Work that repeats on a schedule, or that takes long while the user works on other things, is a job: jobs add, with a name, the ForgeQE command (suite, monitor, run, heal, pr-tests, pack run, pack triage) and every or cron. A job with neither runs one time, now.
+- ForgeQE asks the user to agree to the job before it is added. You MUST NOT add a job the user did not ask for.
+- After you add a job, you SHOULD continue with the other work. Runs that end come in as notices. jobs status and jobs log tell how a job goes.
+- When the user asks how jobs are going, you MUST call jobs list, or jobs status for one job, and MUST NOT guess.
+- A monitor job runs one round each time. It sends its own monitor alerts.
+- To watch a CI pipeline that the team has, add a job on pipeline watch with --github owner/repo --workflow FILE, or --ado-project NAME --pipeline ID, and --branch. It only reads the pipeline.
+- When a pipeline watch or pack run job fails, ForgeQE investigates the failures on local branches. You MUST report each finding as the job reports it: a fix on a branch for review, an app bug, or not decided. You MUST NOT push, merge or delete these branches unless the user asks.
+
 ### ForgeQE itself
 - Questions about what ForgeQE can do, such as "can you do API testing?", are questions, not tasks. You MUST answer them, and MUST NOT start the work.
 - The capability list in "This session" is complete, and says what works in this setup. For details, you MUST call capabilities with the ids that fit.

package/py/forgeqe_engine/copilot_gateway.py

@@ -24,12 +24,14 @@ from __future__ import annotations
 import asyncio
 import hmac
 import json
+import logging
 import os
 import re
 import sys
 import tempfile
 import time
 import uuid
+from logging.handlers import RotatingFileHandler
 from typing import Any, Callable, Dict, List, Optional, TextIO, Tuple
 
 from .systemcerts import use_system_certificates
@@ -40,6 +42,10 @@ KEY_ENV = "FORGEQE_COPILOT_GATEWAY_KEY"
 MAX_BODY = 32 * 1024 * 1024
 # A screenshot step can take minutes on a slow model; past this the request fails rather than hangs.
 REQUEST_TIMEOUT_S = 300.0
+# After a turn ends with its reply (or a call of the caller's tools), how long Copilot gets to say it is idle. Copilot
+# sometimes never does (github/copilot-sdk#2853), which held a request, and every agent waiting on it, for the full
+# REQUEST_TIMEOUT_S.
+TURN_END_GRACE_S = 5.0
 # A tool name as OpenAI and the Copilot SDK take it.
 TOOL_NAME = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
 MAX_TOOLS = 256
@@ -53,6 +59,34 @@ class GatewayError(Exception):
         self.message = message
 
 
+class CallerGone(Exception):
+    """The caller closed the connection (the user pressed Stop): its Copilot session is stopped, nothing is answered."""
+
+
+# What each request did and how long it took, for when Copilot is slow or stuck: never prompts, replies or tokens.
+_log = logging.getLogger("forgeqe.copilot_gateway")
+_log.propagate = False
+
+
+def gateway_log(rid: str, text: str) -> None:
+    _log.info("%s %s", rid, text)
+
+
+def open_gateway_log() -> Optional[str]:
+    """~/.forgeqe/logs/copilot-gateway.log (FORGEQE_HOME), kept to three files of 1 MB."""
+    home = os.environ.get("FORGEQE_HOME") or os.path.join(os.path.expanduser("~"), ".forgeqe")
+    path = os.path.join(home, "logs", "copilot-gateway.log")
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        handler = RotatingFileHandler(path, maxBytes=1_000_000, backupCount=2, encoding="utf-8")
+    except OSError:
+        return None
+    handler.setFormatter(logging.Formatter("%(asctime)s %(message)s"))
+    _log.addHandler(handler)
+    _log.setLevel(logging.INFO)
+    return path
+
+
 # ---------------------------------------------------------------------------------------------------------------------
 # OpenAI chat completions → one Copilot session
 
@@ -337,11 +371,37 @@ class Copilot:
             })
         return out
 
-    async def complete(self, req: Dict[str, Any], on_text: Optional[Callable[[str], None]] = None) -> Dict[str, Any]:
+    async def complete(self, req: Dict[str, Any], on_text: Optional[Callable[[str], None]] = None, gone: Optional["asyncio.Future[Any]"] = None) -> Dict[str, Any]:
         """The answer to one request. With on_text, the reply's text goes to it as Copilot writes it (not for a JSON
-        reply, whose code fences are removed once it is whole)."""
+        reply, whose code fences are removed once it is whole). `gone` completes when the caller hangs up."""
+        rid = uuid.uuid4().hex[:8]
+        started = time.monotonic()
+        gateway_log(rid, f"start model={req['model']} tools={len(req['tools'])} schema={req['schema'] is not None} stream={bool(on_text)}")
+        try:
+            out = await self._complete(rid, req, on_text, gone)
+        except CallerGone:
+            gateway_log(rid, f"caller gone after {time.monotonic() - started:.1f}s: its Copilot session was stopped")
+            raise
+        except GatewayError as e:
+            gateway_log(rid, f"error {e.status} after {time.monotonic() - started:.1f}s: {e.message[:300]}")
+            raise
+        calls = out["choices"][0]["message"].get("tool_calls") or []
+        gateway_log(rid, f"done after {time.monotonic() - started:.1f}s" + (f" calls={','.join(c['function']['name'] for c in calls)}" if calls else ""))
+        return out
+
+    async def _complete(self, rid: str, req: Dict[str, Any], on_text: Optional[Callable[[str], None]], gone: Optional["asyncio.Future[Any]"]) -> Dict[str, Any]:
         from copilot.generated.rpc import PermissionDecisionReject
-        from copilot.session_events import AssistantMessageData, AssistantMessageDeltaData, AssistantUsageData, SessionErrorData
+        from copilot.session_events import (
+            AssistantMessageData,
+            AssistantMessageDeltaData,
+            AssistantTurnEndData,
+            AssistantTurnStartData,
+            AssistantUsageData,
+            SessionErrorData,
+            SessionIdleData,
+        )
+
+        loop = asyncio.get_running_loop()
 
         # The text callback while this request streams; None once it is asked for again without streaming.
         stream: Dict[str, Any] = {"to": None if req["schema"] is not None or req["json_only"] else on_text, "sent": False}
@@ -349,6 +409,27 @@ class Copilot:
         usage = {"input": 0, "output": 0, "cached": 0}
         errors: List[str] = []
         calls: List[Dict[str, Any]] = []
+        # The last root reply without tool requests, and the timer that ends the wait when a turn ends without idle.
+        turn: Dict[str, Any] = {"final": None, "timer": None, "settled": asyncio.Event()}
+
+        def on_loop(fn: Callable[[], None]) -> None:
+            """The SDK may call on_event from a thread of its own; timers and events belong to the server's loop."""
+            try:
+                if asyncio.get_running_loop() is loop:
+                    fn()
+                    return
+            except RuntimeError:
+                pass
+            loop.call_soon_threadsafe(fn)
+
+        def settle_soon() -> None:
+            if turn["timer"] is None:
+                turn["timer"] = loop.call_later(TURN_END_GRACE_S, turn["settled"].set)
+
+        def unsettle() -> None:
+            if turn["timer"] is not None:
+                turn["timer"].cancel()
+                turn["timer"] = None
 
         def on_event(event: Any) -> None:
             data = getattr(event, "data", None)
@@ -362,12 +443,25 @@ class Copilot:
             elif stream["to"] and isinstance(data, AssistantMessageDeltaData) and data.delta_content and not data.parent_tool_call_id:
                 stream["sent"] = True
                 stream["to"](data.delta_content)
+            elif isinstance(data, AssistantMessageData) and not data.parent_tool_call_id:
+                turn["final"] = None if data.tool_requests else event
+            elif isinstance(data, AssistantTurnStartData) and not data.parent_tool_call_id:
+                on_loop(unsettle)
+            elif isinstance(data, AssistantTurnEndData) and not data.parent_tool_call_id:
+                gateway_log(rid, "turn ended" + (" with a call of the caller's tools" if calls else " with a reply" if turn["final"] is not None else ""))
+                if calls or turn["final"] is not None:
+                    on_loop(settle_soon)
+            elif isinstance(data, SessionIdleData):
+                gateway_log(rid, "idle")
 
         tried: set = set()
         reply: Any = None
         for _ in range(MAX_TOOL_RETRIES + 2):
             errors.clear()
             calls.clear()
+            on_loop(unsettle)
+            turn["final"] = None
+            turn["settled"] = asyncio.Event()
             names = {t["name"] for t in req["tools"]}
             tools = relay_tools(req["tools"], calls, replaces=self.replaces & names)
             options: Dict[str, Any] = dict(
@@ -387,15 +481,27 @@ class Copilot:
             )
             failure: Optional[str] = None
             session = None
+            # A session that did not finish cleanly is stopped before it is detached: detaching alone leaves Copilot
+            # working on it in the background.
+            clean = False
             try:
                 session = await self.client.create_session(**options)
-                reply = await session.send_and_wait(req["prompt"], attachments=req["attachments"] or None, response_schema=req["schema"], timeout=REQUEST_TIMEOUT_S)
+                gateway_log(rid, f"session {getattr(session, 'session_id', '?')}")
+                reply, clean = await self._wait(rid, session, req, turn, gone)
             except TimeoutError:
                 raise GatewayError(504, f"GitHub Copilot did not answer within {int(REQUEST_TIMEOUT_S)} seconds.")
+            except CallerGone:
+                raise
             except Exception as e:  # Copilot names a tool it will not take; anything else is reported below.
                 failure = str(e)
             finally:
+                on_loop(unsettle)
                 if session is not None:
+                    if not clean:
+                        try:
+                            await session.abort()
+                        except Exception:
+                            pass
                     try:
                         await session.disconnect()
                     except Exception:
@@ -431,6 +537,33 @@ class Copilot:
         return completion(req["model"], content, usage)
 
 
+    async def _wait(self, rid: str, session: Any, req: Dict[str, Any], turn: Dict[str, Any], gone: Optional["asyncio.Future[Any]"]) -> Tuple[Any, bool]:
+        """
+        The reply, and whether Copilot finished cleanly. Copilot normally says it is idle; when a turn has ended with a
+        reply or a call of the caller's tools and it does not, the reply is taken TURN_END_GRACE_S later. A caller that
+        hangs up ends the wait at once.
+        """
+        waiter = asyncio.ensure_future(
+            session.send_and_wait(req["prompt"], attachments=req["attachments"] or None, response_schema=req["schema"], timeout=REQUEST_TIMEOUT_S)
+        )
+        waiter.add_done_callback(lambda t: t.cancelled() or t.exception())
+        settled = asyncio.ensure_future(turn["settled"].wait())
+        watch = {waiter, settled} | ({gone} if gone is not None else set())
+        try:
+            done, _ = await asyncio.wait(watch, timeout=REQUEST_TIMEOUT_S + 5, return_when=asyncio.FIRST_COMPLETED)
+        finally:
+            settled.cancel()
+        if waiter in done:
+            return waiter.result(), True
+        waiter.cancel()
+        if gone is not None and gone in done:
+            raise CallerGone()
+        if settled in done:
+            gateway_log(rid, f"the turn ended but Copilot did not say it was idle within {TURN_END_GRACE_S:.0f}s: answered anyway")
+            return turn["final"], False
+        raise TimeoutError()
+
+
 # Copilot's own tools that the agent runtime's tools are named like (bash, glob, grep, edit, …). A caller tool with one
 # of these names says it replaces Copilot's: the caller's tool is the one offered, and it runs nothing here.
 BUILTIN_TOOLS = frozenset({"bash", "powershell", "glob", "grep", "view", "edit", "create", "task", "skill", "web_fetch", "think", "update_todo", "report_intent"})
@@ -566,6 +699,13 @@ class Stream:
         self._event({"error": {"message": message, "type": "forgeqe_copilot_gateway"}})
 
 
+async def caller_gone(reader: asyncio.StreamReader) -> None:
+    """Completes when the caller closes the connection. Its callers (the agent runtime, the engine's HTTP client) never
+    half-close, so the end of what it sends is the caller gone."""
+    while await reader.read(4096):
+        pass
+
+
 async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, copilot: Any, key: str) -> None:
     try:
         try:
@@ -608,16 +748,24 @@ async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, cop
             writer.write(_error(400, "The request body is not JSON."))
             return
         req = translate(body)
-        if req["stream"]:
-            stream = Stream(writer, req["model"])
-            try:
-                await stream.finish(await copilot.complete(req, stream.text))
-            except GatewayError as e:
-                await stream.fail(e.status, e.message)
-            except Exception as e:
-                await stream.fail(502, f"GitHub Copilot: {type(e).__name__}: {e}"[:2000])
-            return
-        writer.write(_response(200, await copilot.complete(req)))
+        gone = asyncio.ensure_future(caller_gone(reader))
+        try:
+            if req["stream"]:
+                stream = Stream(writer, req["model"])
+                try:
+                    await stream.finish(await copilot.complete(req, stream.text, gone=gone))
+                except GatewayError as e:
+                    await stream.fail(e.status, e.message)
+                except CallerGone:
+                    raise
+                except Exception as e:
+                    await stream.fail(502, f"GitHub Copilot: {type(e).__name__}: {e}"[:2000])
+                return
+            writer.write(_response(200, await copilot.complete(req, gone=gone)))
+        finally:
+            gone.cancel()
+    except CallerGone:
+        return
     except GatewayError as e:
         writer.write(_error(e.status, e.message))
     except Exception as e:  # The SDK's own errors: report them rather than drop the connection.
@@ -640,6 +788,7 @@ async def serve(out: TextIO, copilot: Any = None) -> int:
         if token.startswith("ghp_"):
             out.write(json.dumps({"error": "GitHub Copilot does not take classic tokens (ghp_): use a fine-grained token with the Copilot Requests permission."}) + "\n")
             return 1
+        open_gateway_log()
         try:
             copilot = Copilot(token or None)
             await copilot.start()
@@ -654,6 +803,7 @@ async def serve(out: TextIO, copilot: Any = None) -> int:
             return 1
     server = await asyncio.start_server(lambda r, w: handle(r, w, copilot, key), host="127.0.0.1", port=0, limit=64 * 1024)
     port = server.sockets[0].getsockname()[1]
+    gateway_log("gateway", f"listening on 127.0.0.1:{port}")
     out.write(json.dumps({"port": port, "login": getattr(copilot, "login", "")}) + "\n")
     out.flush()
     loop = asyncio.get_running_loop()