dsh-session-sync 0.2.32 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,191 @@
1
+ // lib/projection.mjs — 恢复期 cwd 投影表(本地状态;镜像字节保持原样)。
2
+ //
3
+ // 恢复时,跨平台会话被写到宿主布局中的**投影位置**
4
+ // (`<projectKey(投影 cwd)>/<sessionId>/<file>`)并把首帧 cwd 换成本机路径。
5
+ // 同步仓库(镜像)里仍是原设备的 header——投影表只落在本地 `.git/` 下、不进
6
+ // 提交,记录 canonicalRel ↔ projectedRel、原始 cwd 与首帧字节,供推送时把本地
7
+ // 追加尾部接回原首帧(对端看到的仍是逐字节 append)。
8
+ //
9
+ // 不可解析的日志/状态一律"保持原样":本模块绝不猜测字节,也绝不让一份看不懂的
10
+ // 会话变成一次写坏布局的操作。
11
+
12
+ import { promises as fs } from 'node:fs'
13
+ import path from 'node:path'
14
+ import { decodeSegment } from './paths.mjs'
15
+ import { projectCwd, projectedRelOf } from './cwdmap.mjs'
16
+ import {
17
+ SESSION_LOG_NAME_RE,
18
+ encodeSessionHeader,
19
+ isCompressedName,
20
+ readSessionHeader,
21
+ } from './sessionlog.mjs'
22
+
23
+ /** 投影表状态文件(本地、不进提交)。 */
24
+ export const PROJECTION_STATE_FILE = path.join('.git', 'dsh-session-sync-projection.json')
25
+
26
+ const STATE_VERSION = 1
27
+ /** header 首帧的缓存上限:超过就不缓存(推送时退回重新压缩)。 */
28
+ const MAX_HEADER_FRAME_BYTES = 64 * 1024
29
+
30
+ /**
31
+ * 空投影表。
32
+ * @returns {{entries: object[], byCanonical: Map<string, object>, byProjected: Map<string, object>, error?: string}} 投影表。
33
+ */
34
+ function emptyProjection() {
35
+ return { entries: [], byCanonical: new Map(), byProjected: new Map() }
36
+ }
37
+
38
+ /**
39
+ * 由条目数组建投影表(按 canonical/projected 双向索引)。
40
+ * @param {object[]} entries - 投影条目。
41
+ * @returns {{entries: object[], byCanonical: Map<string, object>, byProjected: Map<string, object>}} 投影表。
42
+ */
43
+ function indexProjection(entries) {
44
+ const byCanonical = new Map()
45
+ const byProjected = new Map()
46
+ for (const entry of entries) {
47
+ byCanonical.set(entry.canonicalRel, entry)
48
+ byProjected.set(entry.projectedRel, entry)
49
+ }
50
+ return { entries, byCanonical, byProjected }
51
+ }
52
+
53
+ /**
54
+ * 读取投影表。缺失 = 空表(尚未投影过);损坏 = 空表 + error(fail closed:
55
+ * 不投影、不把本地视图当推送源)。
56
+ * @param {string|undefined} repoDir - 同步仓库根。
57
+ * @returns {Promise<{entries: object[], byCanonical: Map<string, object>, byProjected: Map<string, object>, error?: string}>} 投影表。
58
+ */
59
+ export async function readProjectionState(repoDir) {
60
+ if (typeof repoDir !== 'string' || repoDir.length === 0) return emptyProjection()
61
+ let raw
62
+ try {
63
+ raw = await fs.readFile(path.join(repoDir, PROJECTION_STATE_FILE), 'utf8')
64
+ } catch {
65
+ return emptyProjection()
66
+ }
67
+ let parsed
68
+ try {
69
+ parsed = JSON.parse(raw)
70
+ } catch {
71
+ return { ...emptyProjection(), error: 'projection state is not valid JSON (run a pull to rebuild it)' }
72
+ }
73
+ if (parsed === null || typeof parsed !== 'object' || parsed.version !== STATE_VERSION || !Array.isArray(parsed.entries)) {
74
+ return { ...emptyProjection(), error: 'projection state has an unsupported shape (run a pull to rebuild it)' }
75
+ }
76
+ const entries = []
77
+ for (const entry of parsed.entries) {
78
+ if (entry === null || typeof entry !== 'object') continue
79
+ if (typeof entry.canonicalRel !== 'string' || typeof entry.projectedRel !== 'string') continue
80
+ if (typeof entry.originalCwd !== 'string' || typeof entry.projectedCwd !== 'string') continue
81
+ if (typeof entry.id !== 'string' || typeof entry.readOnly !== 'boolean') continue
82
+ entries.push({
83
+ canonicalRel: entry.canonicalRel,
84
+ projectedRel: entry.projectedRel,
85
+ id: entry.id,
86
+ originalCwd: entry.originalCwd,
87
+ projectedCwd: entry.projectedCwd,
88
+ readOnly: entry.readOnly,
89
+ compressed: entry.compressed === true,
90
+ headerFrame: typeof entry.headerFrame === 'string' ? entry.headerFrame : undefined,
91
+ })
92
+ }
93
+ return indexProjection(entries)
94
+ }
95
+
96
+ /**
97
+ * 写投影表(原子替换;`.git` 不存在时静默跳过——等价于不持久化)。
98
+ * @param {string|undefined} repoDir - 同步仓库根。
99
+ * @param {object[]} entries - 新投影条目。
100
+ * @returns {Promise<void>}
101
+ */
102
+ export async function writeProjectionState(repoDir, entries) {
103
+ if (typeof repoDir !== 'string' || repoDir.length === 0) return
104
+ const target = path.join(repoDir, PROJECTION_STATE_FILE)
105
+ try {
106
+ const st = await fs.stat(path.dirname(target))
107
+ if (!st.isDirectory()) return
108
+ } catch {
109
+ return
110
+ }
111
+ const payload = Buffer.from(`${JSON.stringify({ version: STATE_VERSION, entries: [...entries].sort((a, b) => a.canonicalRel.localeCompare(b.canonicalRel)) })}
112
+ `)
113
+ const temporary = `${target}.${process.pid}.tmp`
114
+ await fs.writeFile(temporary, payload)
115
+ await fs.rename(temporary, target)
116
+ }
117
+
118
+ /**
119
+ * 规划一个镜像文件在恢复时的落盘形态。
120
+ * @param {{content: Buffer, mirrorRel: string, cwdMap: ReadonlyArray<object>, sessionRoot: string, platform?: NodeJS.Platform}} deps - 文件与配置。
121
+ * @returns {{rel: string, content: Buffer, kind: 'as-is'|'mapped'|'placeholder'|'skipped', entry?: object}} 落盘计划。
122
+ */
123
+ export function planRestoreFile(deps) {
124
+ const name = path.posix.basename(deps.mirrorRel)
125
+ const asIs = { rel: deps.mirrorRel, content: deps.content, kind: /** @type {const} */ ('as-is') }
126
+ if (!SESSION_LOG_NAME_RE.test(name)) return asIs
127
+ const compressed = isCompressedName(name)
128
+ const parsed = readSessionHeader(deps.content, compressed)
129
+ if (parsed === undefined || typeof parsed.header.cwd !== 'string') return asIs
130
+ const parts = deps.mirrorRel.split('/')
131
+ // 宿主布局 = <projectKey>/<sessionId>/<file>;旧扁平布局不投影(否则路径语义
132
+ // 不对,宁可不改)。
133
+ if (parts.length < 3) return asIs
134
+ if (decodeSegment(parts[1]) !== parsed.header.id) {
135
+ return { ...asIs, kind: 'skipped' }
136
+ }
137
+ const projection = projectCwd(parsed.header.cwd, {
138
+ map: deps.cwdMap,
139
+ sessionRoot: deps.sessionRoot,
140
+ platform: deps.platform,
141
+ })
142
+ if (!projection.mapped && !projection.unmapped) return asIs
143
+ const rel = projectedRelOf(deps.mirrorRel, /** @type {string} */ (projection.cwd))
144
+ if (rel === undefined || rel === deps.mirrorRel) return asIs
145
+ const header = { ...parsed.header, cwd: projection.cwd }
146
+ const entry = {
147
+ canonicalRel: deps.mirrorRel,
148
+ projectedRel: rel,
149
+ id: parsed.header.id,
150
+ originalCwd: parsed.header.cwd,
151
+ projectedCwd: projection.cwd,
152
+ readOnly: projection.readOnly,
153
+ compressed,
154
+ headerFrame: parsed.frame.length <= MAX_HEADER_FRAME_BYTES ? parsed.frame.toString('base64') : undefined,
155
+ }
156
+ return {
157
+ rel,
158
+ content: Buffer.concat([encodeSessionHeader(header, compressed), parsed.rest]),
159
+ kind: projection.readOnly ? 'placeholder' : 'mapped',
160
+ entry,
161
+ }
162
+ }
163
+
164
+ /**
165
+ * 把本机投影副本还原成镜像字节:镜像里的原首帧 + 本地追加尾部。
166
+ * 占位(只读视图)与 header 被改动的副本一律返回 undefined(永不推送)。
167
+ * @param {{entry: object, localContent: Buffer, mirrorContent?: Buffer}} deps - 投影条目与两侧字节。
168
+ * @returns {Buffer|undefined} 可推送的镜像字节。
169
+ */
170
+ export function canonicalizeProjectedFile(deps) {
171
+ const entry = deps.entry
172
+ if (entry.readOnly === true) return undefined
173
+ if (!Buffer.isBuffer(deps.localContent)) return undefined
174
+ const local = readSessionHeader(deps.localContent, entry.compressed === true)
175
+ if (local === undefined) return undefined
176
+ if (local.header.id !== entry.id) return undefined
177
+ if (local.header.cwd !== entry.projectedCwd) return undefined
178
+ let headerFrame
179
+ if (Buffer.isBuffer(deps.mirrorContent)) {
180
+ const mirror = readSessionHeader(deps.mirrorContent, entry.compressed === true)
181
+ // 镜像 header 可能被对端迁移更新过:优先沿用它的首帧,保证不丢更新。
182
+ if (mirror !== undefined && mirror.header.id === entry.id) headerFrame = mirror.frame
183
+ }
184
+ if (headerFrame === undefined && typeof entry.headerFrame === 'string') {
185
+ headerFrame = Buffer.from(entry.headerFrame, 'base64')
186
+ }
187
+ if (headerFrame === undefined) {
188
+ headerFrame = encodeSessionHeader({ ...local.header, cwd: entry.originalCwd }, entry.compressed === true)
189
+ }
190
+ return Buffer.concat([headerFrame, local.rest])
191
+ }
package/lib/render.mjs CHANGED
@@ -30,6 +30,16 @@ export function renderStatus(status) {
30
30
  if (status.forks.length > 0) {
31
31
  lines.push(` fork files (both-sides-kept conflicts): ${status.forks.slice(0, 10).join(', ')}${status.forks.length > 10 ? ' …' : ''}`)
32
32
  }
33
+ if ((status.cwdMapped ?? 0) > 0 || (status.cwdUnmapped ?? 0) > 0) {
34
+ lines.push(` cwd projection: ${status.cwdMapped ?? 0} mapped to local path(s), ${status.cwdUnmapped ?? 0} unmapped (read-only under ${status.cwdPlaceholder ?? 'sessionRoot/--unmapped--'})`)
35
+ }
36
+ if ((status.followedSymlinks ?? 0) > 0) {
37
+ lines.push(` followed symbolic links inside sessionRoot: ${status.followedSymlinks}`)
38
+ }
39
+ if ((status.skippedSymlinks ?? 0) > 0) {
40
+ const sample = (status.skippedSymlinkPaths ?? []).slice(0, 5).join(', ')
41
+ lines.push(` skipped symbolic links (not mirrored; followSessionSymlinks=${status.followSessionSymlinks === true}): ${status.skippedSymlinks}${sample.length > 0 ? ` — ${sample}${status.skippedSymlinks > 5 ? ' …' : ''}` : ''}`)
42
+ }
33
43
  if (status.diffStat !== '') {
34
44
  lines.push(` diff HEAD..remote:\n${status.diffStat.split('\n').map(line => ` ${line}`).join('\n')}`)
35
45
  }
@@ -62,7 +72,7 @@ export function renderDiff(status) {
62
72
 
63
73
  /**
64
74
  * pull 结果文本。
65
- * @param {{ok: boolean, pulled?: boolean, merged?: boolean, adopted?: number, appended?: number, diverged?: number, forks?: string[], head?: string, error?: string, warnings?: string[]}} result - pull 产物。
75
+ * @param {{ok: boolean, pulled?: boolean, merged?: boolean, adopted?: number, appended?: number, diverged?: number, forks?: string[], head?: string, restored?: number, cwdMapped?: number, cwdUnmapped?: number, error?: string, warnings?: string[]}} result - pull 产物。
66
76
  * @returns {string}
67
77
  */
68
78
  export function renderPull(result) {
@@ -76,6 +86,8 @@ export function renderPull(result) {
76
86
  if ((result.adopted ?? 0) > 0) lines.push(` adopted ${result.adopted} remote-only append(s) (local side was unchanged)`)
77
87
  if ((result.appended ?? 0) > 0) lines.push(` both sides appended in ${result.appended} file(s): local version kept, remote version preserved as fork file(s)`)
78
88
  if ((result.diverged ?? 0) > 0) lines.push(` diverged in ${result.diverged} file(s) (non-append rewrite): local version kept, remote version preserved as fork file(s) — inspect before continuing`)
89
+ if ((result.cwdMapped ?? 0) > 0) lines.push(` cwd projection: ${result.cwdMapped} restored session(s) mapped to a local path (header on disk is local; the mirror keeps the origin device's bytes)`)
90
+ if ((result.cwdUnmapped ?? 0) > 0) lines.push(` cwd projection: ${result.cwdUnmapped} restored session(s) have no cwdMap entry — shown read-only under the --unmapped-- placeholder`)
79
91
  for (const fork of (result.forks ?? []).slice(0, 20)) lines.push(` fork ${fork}`)
80
92
  if ((result.forks ?? []).length > 20) lines.push(` … ${result.forks.length - 20} more`)
81
93
  for (const warning of (result.warnings ?? [])) lines.push(` warning: ${warning}`)
@@ -84,7 +96,7 @@ export function renderPull(result) {
84
96
 
85
97
  /**
86
98
  * push 结果文本。
87
- * @param {{ok: boolean, pushed?: boolean, head?: string, mirrored?: number, deleted?: number, remote?: string, error?: string, warnings?: string[]}} result - push 产物。
99
+ * @param {{ok: boolean, pushed?: boolean, head?: string, mirrored?: number, deleted?: number, remote?: string, skippedSymlinks?: number, skippedSymlinkPaths?: string[], error?: string, warnings?: string[]}} result - push 产物。
88
100
  * @returns {string}
89
101
  */
90
102
  export function renderPush(result) {
@@ -95,6 +107,9 @@ export function renderPush(result) {
95
107
  ` mirrored ${result.mirrored ?? 0} file(s)${(result.deleted ?? 0) > 0 ? `, deleted ${result.deleted} (removed locally)` : ''}`,
96
108
  ` pushed to ${result.remote ?? 'remote'} → head ${result.head ?? ''}`,
97
109
  ]
110
+ if ((result.skippedSymlinks ?? 0) > 0) {
111
+ lines.push(` skipped ${result.skippedSymlinks} symbolic link(s) under sessionRoot (not mirrored; set followSessionSymlinks: true to include links inside the root)`)
112
+ }
98
113
  for (const warning of (result.warnings ?? [])) lines.push(` warning: ${warning}`)
99
114
  return lines.join('\n')
100
115
  }
@@ -0,0 +1,142 @@
1
+ // lib/sessionlog.mjs — 会话日志首帧(header)读取/改写(零 DSH 依赖,仅 node:zlib)。
2
+ //
3
+ // 宿主 session-persistence-jsonl 把每个会话写成一串**独立的 zstd 帧**:第一帧
4
+ // 只含 header 行,之后每个追加批次各一帧(`compression: none` 时是纯 JSONL,
5
+ // header 就是第一行)。追加从不重写已提交帧。因此投影只需要替换第一帧/第一行,
6
+ // 其余字节原样保留——这也让反向投影可以"把镜像里的原首帧接回本地尾部",追加
7
+ // 事件仍逐字节相同(append-only 合并语义不受影响)。
8
+ //
9
+ // 本模块只做结构性扫描与解压/压缩;任何不可解析的输入都返回 undefined,由调用方
10
+ // 保持文件原样(绝不猜测、绝不改写看不懂的字节)。
11
+
12
+ import { constants, zstdCompressSync, zstdDecompressSync } from 'node:zlib'
13
+
14
+ const ZSTD_MAGIC = 0xFD2FB528
15
+ // 与宿主 compressZstdFrame 同参数(带 checksum 的 zstd 帧)。
16
+ const ZSTD_CHECKSUM_OPTIONS = { params: { [constants.ZSTD_c_checksumFlag]: 1 } }
17
+
18
+ /** 宿主会话日志文件名:`session.v<N>.jsonl` 或 `session.v<N>.jsonl.zstd`。 */
19
+ export const SESSION_LOG_NAME_RE = /^session\.v\d+\.jsonl(?:\.zstd)?$/u
20
+
21
+ /**
22
+ * 扩展名是否表示 zstd 编码。
23
+ * @param {string} name - 文件名。
24
+ * @returns {boolean} `.zstd` 结尾为 true。
25
+ */
26
+ export function isCompressedName(name) {
27
+ return typeof name === 'string' && name.endsWith('.zstd')
28
+ }
29
+
30
+ /**
31
+ * 扫描首个完整 zstd 帧的结束偏移(只走结构,不解压)。
32
+ * 参考 zstd 帧格式:magic + frame header descriptor + 可选字段 + blocks + 可选
33
+ * checksum。任何结构损坏/尾部不完整都返回 undefined。
34
+ * @param {Buffer} buffer - 文件字节。
35
+ * @returns {number|undefined} 首帧的排他结束偏移。
36
+ */
37
+ function firstFrameEnd(buffer) {
38
+ let offset = 0
39
+ if (buffer.length < 4) return undefined
40
+ if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) return undefined
41
+ offset += 4
42
+ if (offset === buffer.length) return undefined
43
+ const descriptor = buffer.readUInt8(offset)
44
+ offset += 1
45
+ if ((descriptor & 0x18) !== 0) return undefined
46
+ const contentSizeFlag = descriptor >>> 6
47
+ const singleSegment = (descriptor & 0x20) !== 0
48
+ const checksum = (descriptor & 0x04) !== 0
49
+ const dictionaryFlag = descriptor & 0x03
50
+ const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag
51
+ const contentSizeBytes = contentSizeFlag === 0
52
+ ? (singleSegment ? 1 : 0)
53
+ : 1 << contentSizeFlag
54
+ const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes
55
+ if (buffer.length - offset < remainingHeaderBytes) return undefined
56
+ offset += remainingHeaderBytes
57
+ for (;;) {
58
+ if (buffer.length - offset < 3) return undefined
59
+ const blockHeader = buffer.readUIntLE(offset, 3)
60
+ offset += 3
61
+ const lastBlock = (blockHeader & 1) !== 0
62
+ const blockType = (blockHeader >>> 1) & 0x03
63
+ const blockSize = blockHeader >>> 3
64
+ if (blockType === 0x03) return undefined
65
+ const payloadBytes = blockType === 0x01 ? 1 : blockSize
66
+ if (buffer.length - offset < payloadBytes) return undefined
67
+ offset += payloadBytes
68
+ if (lastBlock) break
69
+ }
70
+ if (checksum) {
71
+ if (buffer.length - offset < 4) return undefined
72
+ offset += 4
73
+ }
74
+ return offset
75
+ }
76
+
77
+ /**
78
+ * 读取会话日志的 header 行(首帧/首行)与其余字节。
79
+ * @param {Buffer} buffer - 文件字节。
80
+ * @param {boolean} compressed - 是否 zstd 编码。
81
+ * @returns {{header: {type: string, id: string, cwd?: string, [key: string]: unknown}, text: string, frame: Buffer, rest: Buffer}|undefined} 解析结果。
82
+ */
83
+ export function readSessionHeader(buffer, compressed) {
84
+ if (!Buffer.isBuffer(buffer)) return undefined
85
+ let frame
86
+ let text
87
+ let rest
88
+ if (compressed) {
89
+ const end = firstFrameEnd(buffer)
90
+ if (end === undefined) return undefined
91
+ frame = buffer.subarray(0, end)
92
+ rest = buffer.subarray(end)
93
+ try {
94
+ text = zstdDecompressSync(frame).toString('utf8')
95
+ } catch {
96
+ return undefined
97
+ }
98
+ } else {
99
+ const newline = buffer.indexOf(0x0a)
100
+ if (newline < 0) return undefined
101
+ frame = buffer.subarray(0, newline + 1)
102
+ text = frame.toString('utf8')
103
+ rest = buffer.subarray(newline + 1)
104
+ }
105
+ if (!text.endsWith('\n')) return undefined
106
+ const line = text.slice(0, -1)
107
+ if (line.length === 0 || line.includes('\n')) return undefined
108
+ let header
109
+ try {
110
+ header = JSON.parse(line)
111
+ } catch {
112
+ return undefined
113
+ }
114
+ if (header === null || typeof header !== 'object' || Array.isArray(header)) return undefined
115
+ if (header.type !== 'session' || typeof header.id !== 'string' || header.id.length === 0) return undefined
116
+ if (header.cwd !== undefined && typeof header.cwd !== 'string') return undefined
117
+ return { header: /** @type {{type: string, id: string, cwd?: string, [key: string]: unknown}} */ (header), text, frame, rest }
118
+ }
119
+
120
+ /**
121
+ * 编码一个 header 行为独立帧(zstd 时与宿主同参数,含 checksum)。
122
+ * @param {{type: string, id: string, [key: string]: unknown}} header - header 对象。
123
+ * @param {boolean} compressed - 是否 zstd 编码。
124
+ * @returns {Buffer} 首帧/首行字节。
125
+ */
126
+ export function encodeSessionHeader(header, compressed) {
127
+ const line = Buffer.from(`${JSON.stringify(header)}\n`, 'utf8')
128
+ return compressed ? zstdCompressSync(line, ZSTD_CHECKSUM_OPTIONS) : line
129
+ }
130
+
131
+ /**
132
+ * 用新 header 替换首帧/首行,其余字节原样保留。
133
+ * @param {Buffer} buffer - 原文件字节。
134
+ * @param {boolean} compressed - 是否 zstd 编码。
135
+ * @param {{type: string, id: string, cwd?: string, [key: string]: unknown}} header - 新 header。
136
+ * @returns {Buffer|undefined} 改写后的字节;输入不可解析时 undefined。
137
+ */
138
+ export function rewriteSessionHeader(buffer, compressed, header) {
139
+ const parsed = readSessionHeader(buffer, compressed)
140
+ if (parsed === undefined) return undefined
141
+ return Buffer.concat([encodeSessionHeader(header, compressed), parsed.rest])
142
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-session-sync",
3
3
  "description": "Cross-device sync for DeepSeek Harness sessions: a dedicated git mirror of the session store, append-only three-way merge with keep-both + fork conflict resolution, /sync command, sync_pull/sync_push/sync_status tools, and configurable auto push/pull",
4
- "version": "0.2.32",
4
+ "version": "0.3.0",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/PerryLink/dsh-session-sync.git"
@@ -129,6 +129,7 @@
129
129
  "@deepseek-ai/dsh-llm": "0.2.2-rc.1",
130
130
  "@deepseek-ai/dsh-session": "0.2.2-rc.1",
131
131
  "@deepseek-ai/dsh-session-format-v3-to-v4": "0.2.2-rc.1",
132
+ "@deepseek-ai/dsh-session-persistence-jsonl": "0.2.2-rc.1",
132
133
  "@deepseek-ai/dsh-storage": "0.2.2-rc.1",
133
134
  "@deepseek-ai/dsh-storage-domain": "0.2.2-rc.1",
134
135
  "@deepseek-ai/dsh-storage-json": "0.2.2-rc.1",
package/types.d.ts CHANGED
@@ -98,6 +98,19 @@ export interface Config {
98
98
  pullIntervalMinutes?: number
99
99
  /** 确认通道:auto(userQuestions 优先,其次 approval)· userQuestions · approval。 */
100
100
  confirmVia?: 'auto' | 'userQuestions' | 'approval'
101
+ /**
102
+ * 恢复期 cwd 投影表(issue #28):`[{ from, to }]`,最长前缀优先,前缀按
103
+ * 路径段边界匹配。命中时恢复出的会话以 `to` 下的本机路径可见;未命中的
104
+ * 跨平台 cwd 归一到 `<sessionRoot>/--unmapped--` 并以只读视图呈现。
105
+ * 同步仓库里的字节始终保留原设备的 cwd。
106
+ */
107
+ cwdMap?: ReadonlyArray<{ from: string, to: string }>
108
+ /**
109
+ * 镜像时是否跟随符号链接(issue #30;默认 false)。只有 realpath 仍落在
110
+ * sessionRoot 内的链接才会被读取/递归;越界链接一律跳过并在 sync_status 里
111
+ * 报告。默认值保持严格的"绝不跟随"。
112
+ */
113
+ followSessionSymlinks?: boolean
101
114
  /** git 子进程终止宽限(ms;默认 10000)。 */
102
115
  graceMs?: number
103
116
  /** 单条 git 命令超时(ms;默认 120000)。 */
@@ -132,6 +145,22 @@ export interface StatusValue {
132
145
  lastPushAt?: number
133
146
  lastError?: string
134
147
  error?: string
148
+ /** 本次镜像跳过的符号链接数(未镜像;default 严格模式)。 */
149
+ skippedSymlinks?: number
150
+ /** 跳过的符号链接路径样本(最多 20 条)。 */
151
+ skippedSymlinkPaths?: string[]
152
+ /** 本次镜像跟随的根内符号链接数(followSessionSymlinks: true 时)。 */
153
+ followedSymlinks?: number
154
+ /** 恢复期投影到本机 cwd 的会话数。 */
155
+ cwdMapped?: number
156
+ /** 无 cwdMap 命中的跨平台会话数(占位只读视图)。 */
157
+ cwdUnmapped?: number
158
+ /** 无法投影的会话文件数(header 不可解析/旧布局)。 */
159
+ cwdProjectionSkipped?: number
160
+ /** 占位只读视图的目录(`<sessionRoot>/--unmapped--`)。 */
161
+ cwdPlaceholder?: string
162
+ /** 是否开启符号链接跟随(诊断用)。 */
163
+ followSessionSymlinks?: boolean
135
164
  warnings?: string[]
136
165
  }
137
166
 
@@ -145,6 +174,9 @@ export interface PullValue {
145
174
  diverged?: number
146
175
  forks?: string[]
147
176
  head?: string
177
+ restored?: number
178
+ cwdMapped?: number
179
+ cwdUnmapped?: number
148
180
  error?: string
149
181
  warnings?: string[]
150
182
  }
@@ -157,6 +189,8 @@ export interface PushValue {
157
189
  mirrored?: number
158
190
  deleted?: number
159
191
  remote?: string
192
+ skippedSymlinks?: number
193
+ skippedSymlinkPaths?: string[]
160
194
  error?: string
161
195
  warnings?: string[]
162
196
  }