Skip to content

feat(session): let listed sessions skip the idle timeout - #16034

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:feat/idle-exempt-sessions
Oct 8, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
unstablebrainiac:feat/idle-exempt-sessions

Conversation

@unstablebrainiac

@unstablebrainiac unstablebrainiac commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An operator can name chats the idle timeout never ends, so a chat that automation wakes stays warm without a keep-alive message.

A chat that only automation wakes, such as one a script cron notifies with session="origin", can go hours between turns. Once it has been idle for session.timeout_secs, the idle sweep ends its process, and the next wake waits for kiro-cli and every MCP server in its agent to start again. Today the ways around that are global or costly: raising session.timeout_secs, or setting it to 0, keeps every idle chat's process running, and messaging the chat before each timeout spends a model turn every time and grows its transcript.

Why it matters

A dispatcher-style chat that should act within a minute of a new event loses that after every quiet stretch, because its next wake starts cold. Raising the global timeout to protect that one chat keeps every other idle chat's process tree resident as well. Keep-alive messages hold the process, but each one is a full model turn added to the chat's history.

Not a goal

  • A per-chat toggle in the dashboard. This is a config setting; a UI control can build on it later.
  • Exempting a session from the RSS recycle (session.watchdog_rss_max_mb) or from the closed-tab reap.
  • Reaping a listed key that no tab ever claimed once its owner is gone, such as a deleted cron job's key. The docs tell the operator to take that key off the list.
  • Keeping a process across a gateway restart.
  • Changing anything for a session that is not listed. The default list is empty.

What changed (motivation → approach → change)

A new setting, session.idle_exempt_keys, names sessions the idle clock never expires, so a chat that automation wakes hours apart keeps its process instead of starting cold on each wake.

Part Change
session.idle_exempt_keys New list of session keys, default []. A dashboard chat's key is dashboard: followed by the sid in its URL; a tab linked to a cron job or a channel thread uses that link's key, such as cron:<job id>.
Idle sweep A listed session is never expired for being idle. The list is read at every sweep, so a change needs no restart.
Closed tab, RSS recycle Unchanged. Closing a listed dashboard or cron tab still ends its process, and so does crossing the RSS ceiling when one is set. A channel thread's session belongs to the channel, so closing its viewer never ends it.
Key with no tab A listed key that no tab ever claimed, such as a cron job that runs without one, is reaped only by the RSS recycle or a gateway restart, even after its job is deleted. The help text and docs say so.
Loader bounds At most 10 keys of up to 512 characters each are kept. 10 is the ceiling session.pool_size already has, and each listed key can keep the same kiro-cli process tree running. A longer key is dropped, not cut short, and the gateway log warns once per load when it drops any.

The idle sweep in SessionCleanup._expire_idle (session_cleanup.py) asks two questions of each session: has it been idle longer than session.timeout_secs, and has the tab that owns it closed. A listed key now answers no to the first question only, so closing a dashboard or cron tab still ends it. The sweep reads the list on every pass, the same way it re-reads the timeout. The field is declared in config/sections.py, where IDLE_EXEMPT_KEYS_MAX is set to POOL_SIZE_MAX. config/loader.py keeps the non-empty strings, stripped, at most IDLE_EXEMPT_KEYS_MAX (10) of them and each at most IDLE_EXEMPT_KEY_MAX_CHARS (512) characters. It drops a longer key rather than cutting it short, since a cut key could match a different session, and loads anything other than a list as no exemptions.

The exemption lives in config rather than in a tool, so a chat cannot keep itself running. The session and config specs, docs/configuration.md and config-baseline.json describe the new setting.

Backwards compatibility

Compatible: the diff adds one optional key with an empty default, and a config that does not set it behaves exactly as before.

Tests

test/test_session_idle_exempt_keys.py:

  • a listed session survives an idle sweep that expires an unlisted session whose key starts with the listed one;
  • a key taken off the list expires at the next sweep;
  • closing a dashboard tab still reaps a listed session;
  • a listed cron: key that no tab ever claimed survives the sweep while a live slot set is published, and an unlisted per-run key of the same job expires;
  • the RSS recycle still resets a listed session over the ceiling;
  • the loader keeps only non-empty stripped strings, loads a non-list as [], and a config.json value reaches session.idle_exempt_keys;
  • the bounds are 10 keys, equal to POOL_SIZE_MAX, and 512 characters: the help text states the 10, and the docs state both;
  • the loader keeps the first 10 keys of a longer list and warns once, naming how many it dropped;
  • a key of exactly 512 characters is kept, a longer one is dropped with no shortened copy kept, and a padded key is measured after stripping;
  • an over-long key takes none of the 10 slots;
  • a list within both bounds loads with no warning.

Twenty-one mutations in a throwaway worktree each failed the tests that guard them: dropping the exemption from the idle check, matching listed keys by prefix or by substring, honouring only dashboard: keys, reading the list once instead of per sweep, extending it to the closed-tab check, reaping a listed key no tab ever claimed, extending it to the RSS recycle, three loader changes (no strip, no list check, keeping empty strings), seven to the bounds (no count limit, no length limit, cutting a key short instead of dropping it, no warning, an over-long key taking a slot, measuring before stripping, warning on a clean list), and three that move a bound (raising the count limit, raising the warm pool ceiling it follows, raising the length limit).

Manual verification

The same idle-check change, with one key hard-coded, ran on a host with session.timeout_secs at 1800, where the sweep runs every 300 seconds. A cron-woken dashboard chat on the list was still running after 37 idle minutes, past the 35 minutes by which the sweep would have ended it. Four unlisted chats that went idle a few minutes earlier had been reaped by then.

The dashboard has no Settings row for the key. Settings rows are hand-written in website/src/pages/settings/*.tsx, and PATCH /api/config/kirocrew accepts no list-typed path, so the key is set in config.json, the same as slack.open_channels.

Related Issues

Closes #16618

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@unstablebrainiac
unstablebrainiac requested a review from a team as a code owner October 1, 2026 23:25
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running labels Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of bf0cef885969725eea9027586360a048a4ed6322 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] bf0cef8

Description read

[DESCRIPTION-READ] 6ea6e7ddd00cb65a6f17a5fe87a7457e5391df5a25ab3dbf0843cf65932bddfb

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed bf0cef885969725eea9027586360a048a4ed6322 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] bf0cef8

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of bf0cef885969725eea9027586360a048a4ed6322 via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The idle exemption is justified by #16618, but the loader's two bounds and their warnings carry no harm a user would hit without them.

Not justified as shipped

  • Item 3 — oversized: the diff says "A longer key is dropped, not cut short… since a cut key could match a different session." That risk exists only because a cut was considered at all. Matching is key not in idle_exempt_keys, an exact frozenset lookup. A 600-character key simply matches no session, so the zero option costs nobody anything.
    Subtraction: delete IDLE_EXEMPT_KEY_MAX_CHARS, overlong_count and its half of the warning, and the three tests for over-long keys.
    Clears when: the length bound is removed, or a named harm from an unbounded key length is shown.
  • Item 4 — inherited: "10 is the ceiling session.pool_size already has" is the symmetry form. The operator who writes this list can already keep every idle process running with session.timeout_secs: 0, so capping their own named keys at 10 protects no boundary.
    Subtraction: delete IDLE_EXEMPT_KEYS_MAX, overflow_count, the warning, and the count-bound tests.
    Clears when: the count cap is removed, or a harm that timeout_secs: 0 does not already allow is named.

What this change ships

Inventory (6 items) — 4 justified

Intent: let an operator keep specific automation-woken chats warm without raising the global timeout or sending keep-alive turns. ADDITION.

  1. New config key session.idle_exempt_keys, default empty — justified
  2. A listed session is never idle-expired; the list is re-read every sweep — justified
  3. Keys over 512 characters are dropped with a log warning — oversized
  4. Only the first 10 keys are kept, with a log warning — inherited (symmetry with POOL_SIZE_MAX)
  5. A non-list value loads as no exemptions — justified
  6. Help text, docs, spec and baseline describe the key — justified

[FIRST-PRINCIPLES-REVIEWED] bf0cef8

Description read

[DESCRIPTION-READ] 5d0e418e5478f7ef43d81b77bf8f7e7f0407a748e684a5f1e3d9f665de886243

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed bf0cef885969725eea9027586360a048a4ed6322 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] bf0cef8

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/idle-exempt-sessions branch from c3670d4 to a51487d Compare October 2, 2026 01:46
@unstablebrainiac

This comment has been minimized.

@unstablebrainiac

This comment has been minimized.

@unstablebrainiac

This comment has been minimized.

@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/idle-exempt-sessions branch from a51487d to 8d32502 Compare October 2, 2026 03:31
@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/idle-exempt-sessions branch from 8d32502 to 1407dc0 Compare October 2, 2026 04:05
@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 2, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/idle-exempt-sessions branch from 1407dc0 to 985d46c Compare October 2, 2026 04:46
@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Oct 2, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Read-only review, holding for a maintainer to accept the new session.idle_exempt_keys setting (no issue linked). The logic is sound: exact match, list re-read every sweep, tab close and the RSS recycle still apply, and agents cannot add keys from the sandbox. Before merge: a listed key with no tab (cron:, or a deleted cron job's key) is never reaped until the RSS limit or a restart; please document that or reap keys matching no live owner, and add a test for a listed key that never had a tab. Consider a lower cap than 64, since each entry can keep a full kiro-cli plus MCP process tree alive.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 3, 2026
@unstablebrainiac
unstablebrainiac force-pushed the feat/idle-exempt-sessions branch from b12fd6f to 10e768b Compare October 3, 2026 22:41
@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

@iamwhatever Both points are handled in 10e768bf358f7155eb637ff4529c96ef884c2c04.

  • A listed key with no tab: documented rather than reaped. The help text, docs/configuration.md and the config and session specs now say that a listed session no tab ever claimed, such as a cron job that runs without one, is reaped only by the RSS recycle (off by default since fix(session): Turn the RSS recycle watchdog off by default #16393) or a gateway restart, even after its job is deleted, so a deleted job's key should come off the list. Reaping keys with no live owner would make the session sweep read the cron store, for the one case where an operator deletes a job and leaves its key. The new test test_a_listed_key_that_never_had_a_tab_outlives_the_sweep lists cron:job-1, publishes a live slot set without it, and checks that the sweep keeps it while an unlisted per-run key of the same job expires. It fails under two mutations: honouring only dashboard: keys, and reaping a listed key no slot ever claimed.
  • The cap: now 10, set to POOL_SIZE_MAX, the ceiling session.pool_size already puts on pre-warmed kiro-cli processes. Each listed key can keep the same thing running: a whole kiro-cli process plus its MCP servers. With the RSS recycle off by default, this count is the only bound on what the list keeps alive. A test pins both bounds, 10 keys and 512 characters, to the numbers the docs state.

The same push rebases the patch onto main 59e8b1e22.

@unstablebrainiac

This comment has been minimized.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 4, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Re-checked at 10e768b: thanks, my earlier asks are addressed (a listed key that no tab ever claimed, such as cron:, is now reaped on the normal timeout and tested; the help text says so). I am still not approving from my side because session.idle_exempt_keys is a new setting with no linked, maintainer-accepted issue; once a maintainer accepts the design this looks ready.

@unstablebrainiac

Copy link
Copy Markdown
Contributor Author

@iamwhatever A listed key no tab ever claimed is not reaped on the normal timeout. This PR took the "document that" option from your review: the help text and docs/configuration.md say such a session is reaped only by the RSS limit, when one is set, or a gateway restart, and test_a_listed_key_that_never_had_a_tab_outlives_the_sweep checks that the sweep keeps it.

The design question is open on #16618, which this PR closes. Triage marked it needs-human because adding the option is a product decision. @bolichen97 @CrysisDeu, that decision is the one thing left on this PR.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 6, 2026
session.idle_exempt_keys names sessions the idle sweep never expires on the
clock, for a chat that automation wakes hours apart. The sweep reads the list
at every pass, so a change needs no restart. A listed session whose tab closes
is still reaped, and the RSS recycle still applies to it. A listed session that
never had a tab, such as a cron job's, is reaped only by that recycle or a
restart, and the docs say so. The loader keeps at most 10 keys, the warm pool's
ceiling, of up to 512 characters each and logs once when it drops any.
@unstablebrainiac
unstablebrainiac force-pushed the feat/idle-exempt-sessions branch from 10e768b to bf0cef8 Compare October 6, 2026 06:59
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 6, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 6, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Reviewed again at the new head, still not approving (crew-pr-reviewer). Letting listed sessions skip the idle timeout is a new feature that changes resource lifetime. A maintainer should accept it.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed on behalf of the maintainers (sweep 2026-10-08): readiness passed, required checks green on bf0cef8, no blocking review threads, security posture unchanged. Approving and merging.

@bolichen97
bolichen97 merged commit e8c0dda into kirodotdev:main Oct 8, 2026
107 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

session: let an operator keep named chats out of the idle timeout

3 participants