Skip to content

fix(skill_hub): date a backfilled install stamp to the install, not the sighting - #1301

Merged
LivXue merged 6 commits into
EverMind-AI:mainfrom
joei4cm:fix/skill_install_meta_backfill_date
Nov 17, 2026
Merged

LivXue merged 6 commits into
EverMind-AI:mainfrom
joei4cm:fix/skill_install_meta_backfill_date

Conversation

@joei4cm

@joei4cm joei4cm commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The second item of #338: a bundle cached before the install stamp existed was stamped the first time it was observed, so its installed_at was the moment of that observation rather than the install. The stamp is never rewritten, so the wrong date froze permanently and raven skill list showed it as a real install date.

write_install_meta now reads installed_at off the bundle directory's mtime -- the last time its entries changed, which is the closest available approximation of the install date. A new field, installed_at_source, records which source produced that date: mtime when the timestamp was measured from the directory, clock when the directory could not be read or its timestamp could not be converted. installed_at keeps its existing ISO format and the list column is unchanged.

A fresh install is unaffected: the bundle directory was just written, so its mtime is the install time. A stamp that already exists is still never rewritten (first install wins).

The first item of #338 -- the blocked-skill marker for the TUI listing -- is left to its own change.

Two details of the mtime route are now explicit. The timestamp is converted inside the guarded block, so a directory mtime the platform cannot represent (Windows rejects values outside roughly 1970 to 3000) falls back to the observation clock instead of raising out of write_install_meta after the bundle is already installed, and that fallback is marked clock. The fresh-install test compares the parsed stamp to a time window, so a run that crosses UTC midnight cannot fail it. The stamp's docstring states the two limits of the approximation: the stamp written into the bundle moves that mtime to the observation moment, and a directory dated in the future records a future date the stamp then keeps.

The fallback still produces an approximate date. When the directory cannot be read, installed_at falls back to the observation clock, which is the date the original bug produced, but the record now says so with installed_at_source: "clock", and first-install-wins still freezes it permanently. A reader that needs a confident install date must treat clock as approximate.

Type

  • Fix
  • Feature
  • Docs
  • CI / tooling
  • Refactor
  • Other

Verification

  • Relevant tests pass locally

  • Relevant lint / type checks pass locally

  • User-facing docs or screenshots are updated when needed (not needed: the stamp keeps its fields and the list column is unchanged)

  • pytest tests/test_skill_hub_policy.py -q -n 0 -> 45 passed (41 before this change; +2 end-to-end install tests, +2 fallback exception cases)

  • pytest tests/ -k "skill_hub or install_meta" -q -n 0 -> 171 passed, 40663 deselected

  • ruff check raven/skill_hub/audit.py tests/test_skill_hub_policy.py -> All checks passed!

  • ruff format --check raven/skill_hub/audit.py tests/test_skill_hub_policy.py -> 2 files already formatted

  • Mutation checks: narrowing except (OSError, OverflowError, ValueError) to except OSError -> 2 failed, 43 passed; removing installed_at_source from the record -> 8 failed, 37 passed; replacing the directory mtime with the observation clock -> 1 failed, 44 passed

  • CI on 8d6334066: 22 pass, 1 skipped (docs deploy), 0 fail

Risk

  • Security impact considered: the change reads a directory timestamp and writes the same field as before plus one source label; no key or credential value is involved.
  • Backward compatibility considered: installed_at keeps its format, and the new installed_at_source is additive. raven skill list, the skills RPC surface and every existing reader of installed_at are unchanged; the RPC surface builds a fixed shape from the stamp and ignores unknown keys. A bundle installed while this change is in force is dated to its directory mtime, which for a fresh install is the install time. A bundle whose directory carries a future mtime -- a restore from a backup, a clock left wrong at install time -- still records a future date, and the never-rewritten stamp keeps it.
  • Fallback risk is marked: when stat() fails or the timestamp cannot be converted, installed_at still falls back to the observation clock, which is the date the original bug produced, and first-install-wins freezes it permanently. Such a record is now distinguishable by installed_at_source: "clock"; readers that need a confident install date must treat it as approximate.
  • Rollback path is clear for risky changes: revert the commits on this branch.

Related Issues

#338

@joei4cm

joei4cm commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Friendly ping for a review when someone has a moment.

CI is fully green at the current head, including the coverage gates, and the branch sits on the latest main.

This is a one-line behavior change with two new tests: installed_at in the hub install stamp is read off the bundle directory mtime instead of the observation clock, so a bundle that was cached before the stamp existed is dated to its install rather than the moment it was first seen. raven skill list and the skills RPC surface read the same fields as before. The other item in #338 is left to its own change.

Happy to address anything in the meantime.

@LivXue LivXue left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Verdict

Mergeable. The backfill now derives installed_at from the bundle directory mtime, and a fresh install still stamps its install time.

What changed

write_install_meta keeps its first-write-wins contract and its record shape. Only the clock read changes: _installed_at stats the skill directory and converts the mtime to a UTC ISO-8601 second, falling back to the clock on OSError. The timestamp is read before the stamp file is written, so the stamp does not date itself.

Checks

  • Fresh installs: the hub client extracts a zip only when <slug>@<version> is absent, writes every member with the current time and never restores archive mtimes, and the RPC installer renames a freshly extracted staging directory. Both leave the bundle root at install time.
  • Later observations are read-only, so normal use does not move the timestamp. An upgrade re-extracts the bundle, but that is pre-existing behaviour and outside this fix.
  • Format and timezone are unchanged (UTC, timespec="seconds", same field), so the CLI, RPC and web readers need no change. Existing stamps are still never rewritten, so this affects future backfills only.
  • pytest tests/test_skill_hub_policy.py -> 40 passed.
  • Mutation: replacing the mtime read with datetime.now(...) fails the backfill test (1 failed, 39 passed).

No blocking findings

The mtime is an approximation: adding or removing an entry at the bundle root after install can move it. The issue accepted this route, and the docstring states the limitation.

@joei4cm
joei4cm force-pushed the fix/skill_install_meta_backfill_date branch from 312e96d to 7267522 Compare November 15, 2026 14:58
joei4cm added a commit to joei4cm/Raven that referenced this pull request Nov 15, 2026
list_skills was the only listing in the catalog that did not filter the
blocklist. load_skills_for_context, the context renderer,
get_always_skills and the pool's registry view all drop blocked skills;
gather_all_skills keeps them on purpose so raven skill list can mark
them. The banner fed by list_skills neither dropped them nor marked
them, so a TUI user saw a blocked skill as if it were active.

Filter list_skills the way every other runtime listing already does.
The shape of each item and gather_all_skills are unchanged.

First item of EverMind-AI#338; the install-meta date half is EverMind-AI#1301.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
@joei4cm
joei4cm force-pushed the fix/skill_install_meta_backfill_date branch from 7267522 to 94d6be8 Compare November 16, 2026 06:30
joei4cm added a commit to joei4cm/Raven that referenced this pull request Nov 16, 2026
list_skills was the only listing in the catalog that did not filter the
blocklist. load_skills_for_context, the context renderer,
get_always_skills and the pool's registry view all drop blocked skills;
gather_all_skills keeps them on purpose so raven skill list can mark
them. The banner fed by list_skills neither dropped them nor marked
them, so a TUI user saw a blocked skill as if it were active.

Filter list_skills the way every other runtime listing already does.
The shape of each item and gather_all_skills are unchanged.

First item of EverMind-AI#338; the install-meta date half is EverMind-AI#1301.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
@joei4cm

joei4cm commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto the latest main (94d6be8 on top of d7c98c1) and CI is green.

write_install_meta stamps installed_at from the bundle directory's mtime, so a bundle cached before the stamp existed gets its install date instead of the date it was first observed. Fresh installs are unaffected and the renderers are untouched.

This is the second of the two items in #338; #1304 covers the first, and the issue stays open until both land.

@joei4cm
joei4cm force-pushed the fix/skill_install_meta_backfill_date branch from 94d6be8 to 97f9f45 Compare November 16, 2026 10:10
joei4cm added a commit to joei4cm/Raven that referenced this pull request Nov 16, 2026
list_skills was the only listing in the catalog that did not filter the
blocklist. load_skills_for_context, the context renderer,
get_always_skills and the pool's registry view all drop blocked skills;
gather_all_skills keeps them on purpose so raven skill list can mark
them. The banner fed by list_skills neither dropped them nor marked
them, so a TUI user saw a blocked skill as if it were active.

Filter list_skills the way every other runtime listing already does.
The shape of each item and gather_all_skills are unchanged.

First item of EverMind-AI#338; the install-meta date half is EverMind-AI#1301.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
@joei4cm

joei4cm commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

A backfilled install stamp now dates the install, not the moment the stamp was first seen.

On the review above: it reads as a comment rather than an approval, so the branch still shows a review as required. If that review was meant as an approval, submitting it with the Approve button is all this needs.

The branch is on the latest main and CI is green.

joei4cm and others added 4 commits November 17, 2026 00:23
…he sighting

A bundle cached before the install stamp existed is stamped the first
time it is observed, so its installed_at became the moment of that
observation. The stamp is never rewritten, so the wrong date froze
permanently and raven skill list showed it as a real install date.

installed_at now comes from the bundle directory's mtime, the last
time its entries changed, which is the closest known approximation of
the install date. A fresh install is unaffected: the directory was
just written, so its mtime is the install time. A directory that cannot
be read falls back to the clock.

Second item of EverMind-AI#338; the blocked-skill marker for the TUI listing is
left to its own change.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
…be converted

_installed_at guarded stat() but not the datetime.fromtimestamp() call
that consumes the result. On Windows the conversion rejects mtimes
outside roughly 1970..3000 with OSError, so such a timestamp escaped
write_install_meta -- a writer whose contract is best-effort -- and the
callers that run it after a bundle is already on disk do not wrap it.
A successful install could be reported as a failure.

Move the conversion into the guarded block and keep the observation
clock as the fallback for any timestamp the platform cannot represent.
The fresh-install test compared the stamp's date prefix against the
clock read after the write. A run that crosses UTC midnight between the
mtime read and the assertion fails for reasons unrelated to the code.
Compare the parsed timestamp to the clock instead.
The installed_at value is derived from the bundle directory's mtime, which
approximates the install date rather than proving it, and two limits of
that approximation were undocumented. The stamp written into the bundle
moves the mtime to the observation moment, so it stops naming the install
as soon as the bundle is stamped. A directory dated in the future records
a future date, and the never-rewritten stamp keeps it.
@LivXue
LivXue force-pushed the fix/skill_install_meta_backfill_date branch from 3b50170 to 324d9f8 Compare November 16, 2026 16:33
@LivXue

LivXue commented Nov 16, 2026

Copy link
Copy Markdown
Member

Windows compatibility review — 324d9f8ed6

Reviewed at head 324d9f8ed6575d2201ad79632ded306946044df9 (base b33b9bc2b7; also carries the two commits added since the previously reviewed head 3b5017014). Scope: the full base-to-head diff (raven/skill_hub/audit.py, tests/test_skill_hub_policy.py), both call sites of write_install_meta, and the Windows timestamp behaviour _installed_at is written around.

No Windows compatibility issue found.

This PR is explicitly Windows-shaped — it targets the case where datetime.fromtimestamp raises on Windows for an mtime outside the platform's convertible range — and that claim holds here:

dir mtime -86400        -> stamp 2026-11-16T19:57:56+00:00 (clock fallback, as the docstring says)
dir mtime -8589934592   -> clock fallback
dir mtime 0             -> 1970-01-01T00:00:00+00:00
dir mtime 32503680000   -> 3000-01-01T00:00:00+00:00
dir mtime 8589934592    -> 2242-03-16T12:56:32+00:00

A negative mtime (a bundle restored from an archive written on a POSIX box, or a FAT-era timestamp) is refused by this host's fromtimestamp with OSError and lands on the clock fallback rather than failing the install, and the stamp's write-then-never-rewrite order is preserved — the mtime is read before .install-meta.json is created, so the directory mtime moving on that write cannot feed back into a later read.

One platform detail worth noting, not a defect: writing the stamp inside the bundle moves that directory's own mtime (measured: 1000000000.0 -> 1794859076.18 on the first call, unchanged on the second). The module docstring already says so, and because the record is written once and read from the file afterwards, the moved mtime is only visible to a later backfill of a different bundle — never to this one. On a coarse-timestamp volume (FAT/exFAT, 2 s granularity) the "fresh install dates the stamp now" test's 60-second window still holds; this volume has 1 s+ resolution.

Verification (native Windows host, Python 3.12.13, shared venv, detached worktree pinned to the head):

  • python -S runner.py tests/test_skill_hub_policy.py -q → 41 passed in 22.97s, including the three new stamp tests (backfilled date, fresh install, unconvertible-mtime fallback).
  • Timestamp probes above, run against the same tree.

Coverage gaps: no real cached-bundle backfill was replayed, so the "bundle cached before stamping existed" case is unit-tested rather than observed on disk; no FAT/exFAT volume was used.

@LivXue LivXue left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

The mtime route is the right call for a backfill, and the conversion now sits inside the guarded block where it belongs. The new tests call the real writer rather than a stand-in, and the main path is pinned: reading the clock instead of the mtime fails the backfill test, and dropping the timezone from the conversion fails both date tests. Two things I would like to settle before this lands.

First, the fallback silently reproduces the bug being fixed. When stat() fails or the timestamp cannot be converted, installed_at is the observation clock again, with nothing in the record distinguishing it from a measured date, and first-install-wins makes it permanent. The same holds for a directory whose mtime is genuinely later than the install, for example a bundle restored from an archive. A field saying which source produced the date, or a clamp to min(mtime, now), would keep a reader from presenting an approximation as fact. Right now only the docstring says the date may be approximate, and the PR description goes further and calls it the real install date. I would soften that sentence, since it lands in the squash commit.

Second, the tests pin _installed_at but not the directory the callers hand it. SkillHubClient.install returns _bundle_root(dest), which is a nested wrapper directory for a wrapped zip and dest itself for a flat one, so the mtime being read differs by layout and nothing covers either shape. A test through install() with both zip shapes would close that.

One more: dropping OverflowError and ValueError from the except clause leaves all 41 tests green, and widening it to except Exception does too, since the one failure-injection case raises OSError only. A case each, or a narrower clause.

A stat failure or an unconvertible timestamp fell back to the observation
clock with nothing in the record distinguishing it from a measured date,
and first-install-wins freezes that date forever. The installed_at_source
field says mtime or clock, so a reader can tell an approximation from a
real install date.

The backfill test asserts the mtime source and the fallback test asserts
the clock source.
A wrapped zip resolves the bundle root to dest/<skill> while a flat zip
keeps dest, so the directory whose mtime dates the stamp differs by
layout. Each shape now installs a fake bundle through SkillHubClient,
asserts the returned root, and stamps it: the date must equal that
directory's mtime and sit within the install window.

The unconvertible-mtime case now covers every exception the guarded block
catches, so narrowing the except clause fails the test.

@LivXue LivXue left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Approving at 8d63340.

All three nonblocking notes are closed, and each is pinned by a test that reddens when the change is withdrawn. installed_at_source now records whether the date was measured from the directory or fell back to the clock, so the fallback that reproduces the original bug is at least distinguishable from a real install date rather than silently frozen; removing the field fails eight tests. Dropping OverflowError and ValueError from the except clause now fails the two new parameterised cases, where before every test stayed green. And the stamp is pinned through SkillHubClient.install() in both bundle layouts, which covers the _bundle_root split between a wrapped zip's dest/<skill> and a flat zip's dest that nothing reached before.

Not clamping future mtimes is the right call: the docstring already declares that behaviour, and a clamp would not have addressed the fallback, which was the actual complaint.

Verification: 45 passed on the file, 171 across the skill-hub and install-meta selection, ruff clean. Description updated, including the sentence that called the date real, and the risk section now carries the fallback permanence rather than leaving it to the docstring.

@LivXue
LivXue merged commit a639935 into EverMind-AI:main Nov 17, 2026
27 checks passed
joei4cm added a commit to joei4cm/Raven that referenced this pull request Nov 18, 2026
list_skills was the only listing in the catalog that did not filter the
blocklist. load_skills_for_context, the context renderer,
get_always_skills and the pool's registry view all drop blocked skills;
gather_all_skills keeps them on purpose so raven skill list can mark
them. The banner fed by list_skills neither dropped them nor marked
them, so a TUI user saw a blocked skill as if it were active.

Filter list_skills the way every other runtime listing already does.
The shape of each item and gather_all_skills are unchanged.

First item of EverMind-AI#338; the install-meta date half is EverMind-AI#1301.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
joei4cm added a commit to joei4cm/Raven that referenced this pull request Nov 18, 2026
list_skills was the only listing in the catalog that did not filter the
blocklist. load_skills_for_context, the context renderer,
get_always_skills and the pool's registry view all drop blocked skills;
gather_all_skills keeps them on purpose so raven skill list can mark
them. The banner fed by list_skills neither dropped them nor marked
them, so a TUI user saw a blocked skill as if it were active.

Filter list_skills the way every other runtime listing already does.
The shape of each item and gather_all_skills are unchanged.

First item of EverMind-AI#338; the install-meta date half is EverMind-AI#1301.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
joei4cm added a commit to joei4cm/Raven that referenced this pull request Nov 18, 2026
list_skills was the only listing in the catalog that did not filter the
blocklist. load_skills_for_context, the context renderer,
get_always_skills and the pool's registry view all drop blocked skills;
gather_all_skills keeps them on purpose so raven skill list can mark
them. The banner fed by list_skills neither dropped them nor marked
them, so a TUI user saw a blocked skill as if it were active.

Filter list_skills the way every other runtime listing already does.
The shape of each item and gather_all_skills are unchanged.

First item of EverMind-AI#338; the install-meta date half is EverMind-AI#1301.

Co-authored-by: Claude (claude-fable-5-1) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants